请求层:HTTP 封装、缓存与错误处理
本篇要点:能写出一个组件不用关心 token、超时、错误形态的请求层,并且说清哪些请求可以安全重试、为什么慢响应会覆盖快响应。 前置:《状态管理:Pinia 3 模块化与持久化》的 Pinia 已经解决"数据放哪",这一章解决"数据怎么拿回来";《构建工具:Vite 8 与 Rolldown 工程配置》的
import.meta.env会在封装里用到。
为什么需要它
2026 年 4 月的一张客服工单:用户搜"退款",结果里混着"退款流程说明"的条目;再搜"退款进度",列表干脆停在上一次的结果不动了,刷新才好。
前端同事复现时发现规律:连续输入时,请求按 退、退款、退款进、退款进度 依次发出,但响应回来的顺序不保证。最慢的那次(退款,命中缓存未建立、后端走全表扫描,1.4 秒)最后到达,把后面两次的结果覆盖了。页面最后显示的是 1.4 秒前那次查询的内容,看起来就像"没反应"。
同一个页面还有第二个症状:弱网下点"提交",按钮转圈 30 秒,最后什么都没发生。因为 axios 的 timeout 默认是 0,含义是不超时,请求就这么挂着,finally 永远不执行,loading 永远不落地。
这两个症状都不是"某个接口写错了",而是请求层缺了三样东西:能主动中止的能力、能分辨错误类型的结果结构、知道哪些请求能重发的规则。把这三样补上,业务代码里就只剩 await getOrder(id) 一行。
核心概念
一个实例,三层职责
请求层的心智模型是三个同心圆。最内层是传输:一个 axios.create() 出来的单例,固定 baseURL、timeout、withCredentials,请求拦截器统一挂 token、语言、X-Trace-Id。中间层是归一化:把 AxiosError 的各种形态(网络断开、超时、401、500、业务码非 0)压成一个带 kind 字段的错误对象,调用方 switch (e.kind) 就能决策,不用去猜 e.response.status 是不是存在。最外层是领域:api/order.ts 里只有函数签名,组件根本不出现 URL。
反例很常见:每个组件自己写 axios.get('/api/order/list?page=' + page),各自判断 res.data.code === 0。等到后端把信封从 {code, data} 改成 {success, result},改的是六十个文件;再加一个埋点 header,又是六十个。这就是为什么传输细节必须收口到一个文件。
取消与竞态
AbortController 是浏览器标准:new AbortController() 拿到 signal,传给 axios 的 signal 选项(axios 1.1 起支持,截至 2026 年 11 月这条 API 未变),调 .abort() 让请求以 CanceledError 结束。关键在前端要区分"取消"和"失败"——被取消的请求不该弹"请求失败"的红色提示,它本来就是我们主动放弃的。
但只靠 abort() 还不够。存在一个竞态窗口:响应字节已经到浏览器、abort() 还没执行的瞬间,回调照样会跑。所以工程上常用两道保险:新请求发出前 abort() 旧的,同时给每次请求编号,回调里比对"我的编号还是不是最新的"。如图 6-1 所示。
图 6-1 慢请求迟到时的丢弃判定
缓存要和竞态分开想。列表页的"回退保持滚动位置"用组件缓存(<KeepAlive>),接口结果缓存则要考虑失效:同一个 cache key 在用户登出后必须清空,否则下一个账号会看到上一个人的数据。这类缓存建议只做两类——同一会话内的短时去重(比如 5 秒内相同 URL 复用同一个 Promise),以及服务端已经给了 ETag / Cache-Control 时交给浏览器。
超时与重试
timeout 管的是"从发出到拿到响应"的整段时间,超时后 axios 会中止请求并抛 ECONNABORTED(fetch 侧对应 AbortSignal.timeout(ms),Node 20 与主流浏览器都支持;要和业务取消合用,用 AbortSignal.any([controller.signal, AbortSignal.timeout(10_000)]))。超时值按接口分级:查询 8–10 秒,导出类 60 秒,上传按大小另算,别用一个全局值糊弄所有接口。
重试的规则比"失败了再试一次"严格得多,因为乱重试会制造二次故障。
| 判断项 | 允许重试 | 不允许 |
|---|---|---|
| 方法语义 | GET / HEAD / OPTIONS,幂等的 PUT / DELETE | 非幂等 POST(下单、支付、发消息) |
| 失败原因 | 网络中断、超时、502 / 503 / 504、429 | 4xx(除 429)、业务码错误、参数校验失败 |
| 次数与间隔 | 最多 2 次,指数退避加随机抖动 | 固定间隔连发、无上限 |
| 附加条件 | 429 时读 Retry-After | 忽略服务端返回的等待时间 |
退避的实际数字:基数 300 毫秒、倍数 2、抖动 0–100 毫秒,得到约 300、600 毫秒两次机会,最坏多花 1 秒。抖动是必须的——没有抖动,一百个客户端会在同一毫秒重发,把刚恢复的服务再打挂。对于确实需要重试的 POST,正确做法是让后端支持幂等键(Idempotency-Key),同一个键重复提交只处理一次,前端才敢重发。
错误分级
错误不该在拦截器里统一弹 toast,因为不同错误该由不同层处理。
| 层级 | 典型信号 | 处理位置 | 用户看到 |
|---|---|---|---|
| 网络不可达 | ERR_NETWORK、Failed to fetch | 请求层自动重试一次 | 顶部横条"网络异常,已重试" |
| 超时 | ECONNABORTED、TimeoutError | 请求层 + 页面 | "请求超时,点此重试" |
| 鉴权失效 | 401、token 过期 | 全局拦截器 | 跳登录页,带 redirect 参数 |
| 权限 / 不存在 | 403、404 | 路由或页面 | 403 / 404 页 |
| 业务校验 | HTTP 200 但业务码非 0、422 | 表单组件 | 字段下方红字 |
| 服务端错误 | 5xx | 兜底 + 上报 | 通用错误页,附 traceId |
原则只有一条:在能修复它的那一层处理它。字段校验错误只有表单知道该标哪个字段,401 只有全局知道怎么跳转,5xx 谁都不知道怎么办,所以交给兜底并上报。
接口类型与 mock
TypeScript 在编译期起作用,运行时它什么都不保证。后端的 amount 今天是 number,明天可能因为 BigDecimal 序列化成字符串,类型声明不会变,页面就静默错。工程上的做法是两件事并行:用类型描述约定(interface Order),在边界处用 zod 或 valibot 解析一次。解析成本集中在一次遍历,换来的是坏数据在进入组件之前就抛错,并带上字段路径。
mock 选型上,MSW(Mock Service Worker)在网络层拦截,用的是 Service Worker,组件代码、请求代码都不改一行,同一套 handler 能在浏览器、Vitest、Storybook 里共用。相比之下,vite-plugin-mock 走本地 Node 中间件,路径重写、cookie、跨域行为都和真实环境有偏差;在拦截器里写 if (import.meta.env.DEV) return fake 是最差的一种,生产包里留着永远走不到的分支。
动手实践
第一步,准备依赖。 pnpm add axios && pnpm add -D msw,执行 pnpm dlx msw init public/ 生成 mockServiceWorker.js。预期输出:终端打印 Worker script saved to public/mockServiceWorker.js。
第二步,写传输与归一化。 新建 src/api/client.ts:
import axios, { AxiosError, type AxiosRequestConfig } from 'axios'
export type ErrorKind = 'network' | 'timeout' | 'auth' | 'client' | 'server' | 'business'
export class ApiError extends Error {
constructor(
readonly kind: ErrorKind,
readonly status: number,
message: string,
readonly traceId?: string,
) {
super(message)
this.name = 'ApiError'
}
}
export const http = axios.create({
baseURL: import.meta.env.VITE_API_BASE,
timeout: 10_000,
})
http.interceptors.request.use((config) => {
const token = localStorage.getItem('token')
if (token) config.headers.Authorization = `Bearer ${token}`
return config
})
function toApiError(err: AxiosError): ApiError {
if (err.code === 'ECONNABORTED' || err.code === 'ETIMEDOUT') {
return new ApiError('timeout', 0, '请求超时')
}
if (!err.response) return new ApiError('network', 0, '网络不可达')
const { status, data } = err.response as { status: number; data: any }
if (status === 401) return new ApiError('auth', status, '登录已过期')
if (status >= 500) return new ApiError('server', status, '服务暂不可用', data?.traceId)
return new ApiError('client', status, data?.message ?? `请求失败 ${status}`)
}
http.interceptors.response.use(
(res) => {
const body = res.data
// 业务信封:{ code, data, message, traceId },code 非 0 也算失败
if (body && typeof body === 'object' && 'code' in body) {
if (body.code !== 0) {
throw new ApiError('business', res.status, body.message ?? '业务处理失败', body.traceId)
}
return body.data
}
return body
},
(err: AxiosError) => {
if (axios.isCancel(err)) throw err // 取消不是错误,原样抛
throw toApiError(err)
},
)
// 拦截器改了返回值,类型要靠第二个泛型参数补回来
export const get = <T>(url: string, config?: AxiosRequestConfig) =>
http.get<T, T>(url, config)
// 调用 get<Order[]>('/orders', { timeout: 1 }) 后 catch 到的对象:
// ApiError { name: 'ApiError', kind: 'timeout', status: 0, message: '请求超时' }预期输出:e 是 ApiError 实例,kind 为 'timeout',status 为 0(超时拿不到响应体),message 为 请求超时;调用方 switch (e.kind) 就能决定是重试、跳登录还是提示字段错误。
注意 http.get<T, T> 的双泛型:响应拦截器返回的是 res.data,但 axios 的类型签名仍认为返回 AxiosResponse<T>,不补第二个泛型,调用方会拿到 res.data.data 这种不存在的属性。
第三步,写带取消与序号守卫的组合式函数。 新建 src/composables/useLatestRequest.ts:
import { ref, shallowRef } from 'vue'
import type { AxiosRequestConfig } from 'axios'
import { get } from '@/api/client'
export function useLatestRequest<T>(url: () => string, config?: AxiosRequestConfig) {
const data = shallowRef<T | null>(null)
const loading = ref(false)
const error = ref<unknown>(null)
let controller: AbortController | null = null
let seq = 0
async function run() {
controller?.abort() // 第一道保险:主动放弃上一跳
controller = new AbortController()
const mySeq = ++seq
loading.value = true
try {
const res = await get<T>(url(), { ...config, signal: controller.signal })
if (mySeq !== seq) return // 第二道保险:迟到的直接丢
data.value = res
error.value = null
} catch (e) {
if (mySeq === seq) error.value = e // 自己过期的失败不写入
} finally {
if (mySeq === seq) loading.value = false
}
}
return { data, loading, error, run }
}预期输出:把 url 接到输入框,模拟输入框依次触发三次 run(),控制台只在最后一次打印 data;被中断的两次在 catch 里拿到 CanceledError,被序号判断挡掉,页面 error 保持 null,用户看不到任何报错提示。
第四步,用 MSW 复现竞态。 新建 src/mocks/handlers.ts:
import { http as mswHttp, HttpResponse } from 'msw'
export const handlers = [
mswHttp.get('/api/search', async ({ request }) => {
const q = new URL(request.url).searchParams.get('q') ?? ''
await new Promise((r) => setTimeout(r, q.length < 4 ? 1400 : 120)) // 短查询故意慢
return HttpResponse.json({ items: [`${q} 的结果`] })
}),
]预期输出:在 main.ts 里 await worker.start() 后,快速把输入框从 退 打到 退款进度。网络面板里能看到两条请求,第一条标记为 (canceled);页面最终稳定在 退款进度 的结果。把 if (mySeq !== seq) return 注释掉再试,页面会回退成 退款 的结果。
常见误解
"失败就重试,反正重试能提高成功率。" 重试只对幂等且暂时性的失败有意义。给"提交订单"加重试,用户可能被扣两次钱;给 400 加重试,一百次都是同样的 400,只是把错误日志放大一百倍。更隐蔽的是没有退避的重试:客户端在同一毫秒重发,服务端刚恢复就被打回去,故障时间被自己拉长。
"拦截器里 catch 住错误就算处理了。" 拦截器里 catch 之后不 throw,调用方的 await 会拿到 undefined,于是 order.items.map() 抛 Cannot read properties of undefined,报错信息偏离真实原因几十行。拦截器只做归一化和全局副作用(跳登录、上报),处理完必须 throw 回去,让调用方知道这次没成功。
"fetch 没有 timeout 参数,只能手写 setTimeout 再 abort()。" 手写版最常见的两个毛病:请求成功后忘了 clearTimeout,跑一天攒下几百个悬挂的定时器;以及超时和业务取消共用一个 controller,取消过一次之后,这个 controller 上的后续请求会全部立刻失败。标准给的 AbortSignal.timeout(ms) 省掉这段逻辑,和业务取消合并就用 AbortSignal.any([controller.signal, AbortSignal.timeout(10_000)])。还要记住两者的错误名不同:手动 abort() 抛 AbortError,timeout() 触发的是 TimeoutError,判断分支不能只认一个名字。
小结
- 传输细节收口到一个
axios实例:拦截器负责 token 与解包,归一化函数负责把错误压成带kind的对象。 - 取消用
AbortController,竞态用"abort 旧的 + 序号比对"两道保险;被取消的请求不算失败,不提示。 - 重试要同时满足幂等、暂时性失败、有退避抖动、有次数上限,非幂等的
POST靠幂等键而不是重试。 - 错误在能修复它的层处理:
401归全局,字段校验归表单,5xx归兜底并上报。 - 类型只保编译期,接口边界用 zod 解析一次;mock 用 MSW 拦住网络层,别把假数据写进业务代码。
相关主题
请求层把数据拿回来之后,《组件库与设计系统:从零封装可复用组件》要解决的是"同一类界面画六十遍"的问题:组件库与设计系统:从零封装可复用组件。那一章会用这一章的 ApiError 做错误提示组件的输入,也会讲清一个组件库怎样才能既按需引入、又真的被 Tree Shaking 掉。