HTTP 请求
讲解前端请求封装(src/lib/http.ts)的统一约定,包括请求地址分流、请求头注入、401 刷新重试与错误提示。
新增接口或排查一个请求为什么没带 Token、为什么弹了「登录状态已失效」时,读这页。前端所有接口请求都经过 src/lib/http.ts 的封装对象发出,业务代码不直接调 fetch。这一层统一处理请求地址、请求头注入、双令牌刷新、错误提示四件事。
基本用法
API 定义集中在 src/lib/api/ 下,按后端模块分文件(auth.ts、user.ts、dict.ts、role.ts 等)。每个文件从 @/lib/http 导入封装对象,用 get / post / put / patch / del 拼出接口函数。
// src/lib/api/goods.ts(结构摘自 lib/api/dict.ts,实体做了改名)
import { http } from '@/lib/http'
import type { PageResp } from './types'
export type GoodsPageQuery = {
name?: string
page: number
size: number
}
export interface GoodsResp {
id: string | number
name: string
status: 1 | 2
}
export function listGoods(query: GoodsPageQuery, signal?: AbortSignal) {
return http.get<PageResp<GoodsResp>>('/example/goods', { query, signal })
}
export function createGoods(body: { name: string; status: 1 | 2 }) {
return http.post('/example/goods', body)
}
export function deleteGoods(id: string | number) {
return http.del('/example/goods', { body: { ids: [id] } })
}封装对象的方法如下(src/lib/http.ts:381)。
| 方法 | 说明 |
|---|---|
get / post / put / patch / del | 常规请求,泛型标注响应类型,成功时已解包到 data 字段 |
downloadFile | 文件下载:解析 Content-Disposition 文件名,401 时先刷新再重试一次 |
成功响应直接返回 ApiResponse.data,页面拿到的已经是业务数据;失败时抛 ApiError(src/lib/http.ts:44),携带 code(后端业务码)、status(HTTP 状态)与 notified(是否已弹过提示)三个字段。
后端统一响应结构由 Starter 全局响应封装:{ success, code, msg, data, timestamp }。业务失败返回 HTTP 200 加 success: false,封装检查 success 字段后抛错;Access Token 过期返回 HTTP 401,走刷新流程(见下文)。
请求地址与超时
BASE_URL 在 src/lib/http.ts:13 合成:
const BASE_URL = (import.meta.env.VITE_API_PREFIX || import.meta.env.VITE_API_BASE_URL || '').replace(/\/+$/, '')开发环境取 VITE_API_PREFIX(默认 /api),请求先打到同源前缀,再由 vite.config.ts 的 server.proxy 转发到 VITE_API_BASE_URL 并剥掉前缀。同源的意义在于让后端写入的 HttpOnly Refresh Token Cookie 是第一方 Cookie,刷新流程不需要额外配置。生产环境不设置前缀变量,请求直连 VITE_API_BASE_URL 的完整域名,跨域由后端 CORS 配置放开。取值见环境变量参考。
请求超时 30 秒(REQUEST_TIMEOUT_MS,src/lib/http.ts:14),用 AbortSignal.timeout 实现;调用方传入的 signal 与超时信号经 AbortSignal.any 叠加,两者任一触发都会取消请求。
请求头注入
每个请求经 buildHeaders(src/lib/http.ts:131)注入三类头。
Content-Type: application/json,FormData 请求体除外。Authorization 取 auth-session.ts 的 Access Token,拼成 Bearer <token>。X-Tenant-Id 取登录响应写入的租户 ID,租户 ID 存在时注入,对应后端多租户插件的行级隔离。
三类路径例外(TENANT_FREE_PATHS,src/lib/http.ts:19):/auth/login、/auth/refresh、/auth/logout 不携带 X-Tenant-Id,这些请求要么以服务端 Refresh Session 为准,要么以用户显式输入的租户编码为准。账号登录的租户编码走另一个头,由接口函数显式传入(src/lib/api/auth.ts:18):
export function login(req: AccountLoginReq, tenantCode?: string) {
return http.post<LoginResp>('/auth/login', req, {
headers: tenantCode ? { 'X-Tenant-Code': tenantCode } : undefined,
skipAuthRefresh: true,
silent: true
})
}登录密码在调用前经 src/lib/crypto.ts 的 encryptByRsa 用 VITE_APP_RSA_PUBLIC_KEY 加密(PKCS#1 v1.5 填充,与后端私钥配对)。
会话与令牌存储
Access Token 与租户 ID 存在 src/lib/auth-session.ts 的模块级变量里,同时按 persist 标志写入 localStorage(键 continew.access-token / continew.tenant-id),浏览器刷新后经 hydrateSession() 恢复。Refresh Token 不在前端持有,由后端写入 HttpOnly Cookie,刷新请求靠 credentials: 'include' 自动携带。src/lib/cookie.ts 的 setClientCookie / getClientCookie 是外观偏好用的普通 Cookie 工具,与认证 Cookie 无关。
会话每次被替换或清空(setSession / clearSession),authGeneration 计数器加一。请求发起时记录当时的代次,响应回来后经 assertGeneration 比对,代次不一致说明期间用户重新登录或登出了,抛「登录状态已变更,请重试」(SESSION_CHANGED),避免旧请求的响应写进新会话。
401 处理与双令牌刷新
请求收到 HTTP 401 时走刷新重试分支(src/lib/http.ts:284),流程如下。
首次 401 触发 POST /auth/refresh 刷新请求,浏览器自动携带 HttpOnly Cookie。并发 401 共用同一个 Promise(refreshState,src/lib/http.ts:183),Refresh Token 不会被并发轮换。
刷新成功后写回新的 Access Token 与租户 ID,原请求换新 Token 重发一次(isRetry 标记防住重试风暴)。
刷新失败即视为会话终态:handleSessionExpired(src/lib/http.ts:201)清空本地会话,用 keepalive 发一次 POST /auth/logout 让服务端清掉 Cookie,然后交给会话失效回调。
会话失效回调在 src/stores/auth/auth-provider.tsx:47 注册:弹出错误提示,取消进行中的查询,清空认证状态、页签与查询缓存,跳转 /auth/login 并带上当前地址作为 redirect 参数(src/lib/end-session.ts)。
会话失效的提示与跳转由请求层驱动。浏览器刷新后 Token 从 localStorage 恢复(hydrateSession,src/main.tsx:11),路由守卫只在完全没有 Token 时直接跳登录页(不弹提示);只要 Token 存在,哪怕已经过期,请求都会先走一遍刷新流程,刷新也失败才提示并回到登录页。
接口可以显式退出刷新流程:skipAuthRefresh: true 时 401 直接按会话失效抛出,登录、登出等认证接口都这样声明,避免刷新逻辑递归触发。
403 处理
HTTP 403 触发 forbiddenHandler(src/lib/http.ts:293),回调在 auth-provider.tsx:58 注册,把页面替换到 /unauthorized。文件下载的 403 走同一回调。
错误提示
非 401 的失败按状态码映射到中文提示(STATUS_MESSAGE,src/lib/http.ts:25:403「拒绝访问(403)」、500「服务器错误(500)」等),映射不到时给通用兜底文案;响应体里的 msg / message 字段优先于映射文案。提示经 src/components/ui/toast 弹出,ApiError.notified 标记防止同一条错误重复弹。
请求层之外手动上报错误用 reportError:已弹过提示的错误不再重复弹,其余兜底「操作失败,请重试」。silent: true 可以让单个接口不自动弹提示(登录失败由登录页自己刷新验证码并提示,就用这个选项)。
网络层失败提示「网络连接失败,请检查您的网络」。调用方主动取消的请求(React Query 换键或卸载时中止)原样抛出,不当网络故障弹提示。
downloadFile 对失败的下载做了两步兜底:响应是 JSON 时按业务错误解析 msg 并抛出,避免错误被当文件吞掉;响应正常时从 Content-Disposition 解析文件名(兼容 filename*=UTF-8'' 与带引号两种格式)。
TanStack Query 缓存约定
列表与详情的请求、缓存、失效由 TanStack Query 管理,请求封装只负责单次 HTTP 行为。全局默认值在 src/lib/query-client.ts:staleTime 5 分钟,窗口聚焦、重连、组件重挂载都不触发自动重新请求,刷新由工具栏的刷新按钮显式触发;查询失败最多重试 1 次,Mutation 不重试。详情抽屉打开必须展示最新数据,对应的 DETAIL_STALE_TIME_MS 为 0(src/hooks/use-detail-query.ts)。
查询键按层级工厂组织在 src/lib/query-keys.ts,形如 userKeys.list(query)、userKeys.detail(id)。写新接口时先在这里加一组键工厂,Mutation 成功后用 all / lists 前缀做失效:
// 前缀失效:一条 Mutation 让全部用户列表回到初始状态
queryClient.invalidateQueries({ queryKey: userKeys.all })新增接口的建议
在 src/lib/api/ 对应模块文件里追加函数,遵循既有约定:路径常量或字面量拼 URL、泛型标注响应类型、分页参数走 query。新模块的查询键在 src/lib/query-keys.ts 登记。
不要在页面组件里直接调 fetch,绕过封装意味着丢掉 Token 注入、租户头、401 刷新和错误提示。
相关源码
- src/lib/http.ts:请求封装本体(地址合成、刷新、错误提示)
- src/lib/auth-session.ts:Access Token 存储与认证代次
- src/lib/api/:API 定义全目录
- src/lib/query-keys.ts:查询键工厂
- src/stores/auth/auth-provider.tsx:会话失效与 403 回调的注册处