ContiNew
前端开发

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 刷新和错误提示。

相关源码

目录