Vue / 系统课时
封装响应拦截器
封装响应拦截器
本课把后端统一响应转换成页面可直接使用的数据,并将业务失败与 HTTP、网络异常拆成稳定的错误对象。完成后,组件不再反复判断响应码,也不会把不同类型的失败混在一起处理。
学习目标
- 理解响应拦截器与页面组件的职责边界
- 区分业务错误、HTTP 错误、超时与断网
- 封装类型稳定的
request<T>请求函数
明确拦截器的责任边界
管理后台常见的成功响应并不是直接返回业务数据,而是返回 { code, message, data }。因此,HTTP 状态为 200 只代表请求成功到达服务器,不代表业务操作一定成功。
响应层只做三件事:识别统一响应结构、把成功结果收敛为 T、把失败转换成结构化错误。弹窗、跳转登录页和页面空状态属于界面策略,不应直接写进响应拦截器,否则请求模块会依赖具体 UI 组件,也容易产生重复提示。
设计稳定的数据与错误出口
页面应只接收两种结果:成功时得到业务数据 T;失败时收到 ApiError。错误对象保留 kind、HTTP 状态、业务码和请求追踪号,供后续反馈层判断,但不会把整个 Axios 响应泄漏给组件。

实现类型安全的请求模块
下面是项目内的主示例,保存为 src/utils/request.ts。它依赖 axios,属于项目代码片段;放入已配置 TypeScript 路径别名的 Vue 3 项目后即可使用。
import axios, {
type AxiosError,
type AxiosRequestConfig
} from 'axios'
interface ApiEnvelope<T> {
code: number
message: string
data: T
requestId?: string
}
export type ApiErrorKind =
| 'BUSINESS'
| 'HTTP'
| 'AUTH'
| 'SERVER'
| 'TIMEOUT'
| 'NETWORK'
| 'PROTOCOL'
export class ApiError extends Error {
constructor(
message: string,
public readonly kind: ApiErrorKind,
public readonly status?: number,
public readonly code?: number,
public readonly requestId?: string
) {
super(message)
this.name = 'ApiError'
}
}
const client = axios.create({
baseURL: '/api',
timeout: 10_000
})
function isApiEnvelope(value: unknown): value is ApiEnvelope<unknown> {
return (
typeof value === 'object' &&
value !== null &&
typeof (value as Partial<ApiEnvelope<unknown>>).code === 'number' &&
typeof (value as Partial<ApiEnvelope<unknown>>).message === 'string' &&
'data' in value
)
}
client.interceptors.response.use(
(response) => {
const body: unknown = response.data
if (!isApiEnvelope(body)) {
throw new ApiError(
'响应格式不符合约定',
'PROTOCOL',
response.status
)
}
// HTTP 成功后仍要检查业务码,避免把失败数据当成正常结果。
if (body.code !== 0) {
throw new ApiError(
body.message || '业务处理失败',
'BUSINESS',
response.status,
body.code,
body.requestId
)
}
return response
},
(error: AxiosError<ApiEnvelope<unknown>>) => {
if (error.code === 'ECONNABORTED') {
return Promise.reject(new ApiError('请求超时', 'TIMEOUT'))
}
if (!error.response) {
return Promise.reject(new ApiError('网络连接失败', 'NETWORK'))
}
const { status, data } = error.response
const kind: ApiErrorKind =
status === 401 ? 'AUTH' : status >= 500 ? 'SERVER' : 'HTTP'
return Promise.reject(
new ApiError(
'请求未成功完成',
kind,
status,
data?.code,
data?.requestId
)
)
}
)
export async function request<T>(
config: AxiosRequestConfig
): Promise<T> {
const response = await client.request<ApiEnvelope<T>>(config)
return response.data.data
}预期结果
成功且 code 为 0:request<User[]> 返回 User[]
HTTP 200 但 code 非 0:抛出 kind=BUSINESS 的 ApiError
HTTP 401:抛出 kind=AUTH、status=401 的 ApiError
响应结构不合法:抛出 kind=PROTOCOL 的 ApiError
超时或无响应:分别抛出 TIMEOUT 或 NETWORK实际请求时间、接口路径和追踪号可能不同;日志中可分别使用 <TIME>、<PATH>、<ID> 表示动态值。
在页面中验证返回类型
页面调用时无需访问 response.data.data,也不要再次判断业务码。下面是调用方式;错误先交给下一层统一处理,本课只验证成功出口。
interface User {
id: number
name: string
}
const users = await request<User[]>({
method: 'GET',
url: '/users'
})
console.log(users[0]?.name)预期输出
Alice接口真实数据可能不同,但 users 的类型始终是 User[],而不是 Axios 响应对象。
关键边界
不要在成功拦截器里吞掉格式异常。如果后端偶尔返回非统一结构,应把它视为 PROTOCOL 契约错误并明确失败,而不是返回 undefined。同时,不要直接把服务端堆栈、SQL 信息或原始响应体写进 ApiError.message;调试字段可进入受控日志,页面只使用经过筛选的信息。