Vue / 系统课时
请求与响应拦截
请求与响应拦截
接口层如果让每个业务函数自行拼令牌、追踪标识、判断错误码和解包数据,很快会出现重复逻辑与返回类型不一致。本课用 Axios 实例建立统一管线,让横切逻辑集中,同时保留清晰的 TypeScript 类型边界。
学习目标
- 用请求拦截器统一注入认证令牌与追踪标识
- 用响应拦截器归一化 HTTP 错误和业务错误
- 用类型化请求包装器完成响应解包,避免运行时结果与静态类型不一致
划清拦截器的职责
请求拦截器适合处理“每次请求都要做”的事情,例如追加 Authorization、生成 X-Trace-Id、补充语言或租户信息。响应拦截器适合把 HTTP 失败和业务失败转换成统一错误,让页面不必理解 Axios 的错误结构。
响应解包要特别注意类型。直接在响应拦截器里把 AxiosResponse<T> 替换成裸 T,运行时虽然方便,却会让 Axios 原有类型声明与真实返回值脱节。更稳妥的做法是:拦截器负责校验与归一化,薄包装器 request<T>() 再集中返回 data。

建立类型化请求管线
下面示例使用自定义 adapter 模拟服务端,因此不依赖真实接口;在已安装 Axios 的 TypeScript 项目中可直接运行。请求拦截器只修改配置,响应拦截器只判断失败,request<T> 负责把统一响应结构解包为业务类型。
import axios, {
AxiosHeaders,
type AxiosAdapter,
type AxiosRequestConfig,
type AxiosResponse,
} from "axios";
type ApiEnvelope<T> = {
code: number;
message: string;
data: T;
};
class AppError extends Error {
constructor(
public readonly code: string,
message: string,
public readonly status?: number,
) {
super(message);
}
}
const adapter: AxiosAdapter = async (config): Promise<AxiosResponse> => {
const headers = AxiosHeaders.from(config.headers);
console.log("authorization attached:", Boolean(headers.get("Authorization")));
console.log("trace attached:", Boolean(headers.get("X-Trace-Id")));
return {
data: { code: 0, message: "ok", data: { id: 7, name: "Ada" } },
status: 200,
statusText: "OK",
headers: new AxiosHeaders(),
config,
};
};
const http = axios.create({ baseURL: "/api", timeout: 8000, adapter });
http.interceptors.request.use((config) => {
const token = "demo-token";
config.headers.set("Authorization", `Bearer ${token}`);
config.headers.set("X-Trace-Id", crypto.randomUUID());
return config;
});
http.interceptors.response.use(
(response) => {
const body = response.data as ApiEnvelope<unknown>;
if (body.code !== 0) {
throw new AppError(`BIZ_${body.code}`, body.message, response.status);
}
return response;
},
(error: unknown) => {
if (axios.isAxiosError<ApiEnvelope<unknown>>(error)) {
throw new AppError(
"HTTP_ERROR",
error.response?.data?.message ?? error.message,
error.response?.status,
);
}
throw error;
},
);
async function request<T>(config: AxiosRequestConfig): Promise<T> {
const response = await http.request<ApiEnvelope<T>>(config);
return response.data.data;
}
async function main() {
const user = await request<{ id: number; name: string }>({
method: "GET",
url: "/users/7",
});
console.log("user:", user.id, user.name);
}
main().catch(console.error);预期输出
authorization attached: true
trace attached: true
user: 7 Ada示例中的追踪 ID 实际值每次都不同,因此验证重点是请求头已被注入,而不是固定某个 <ID>。
统一错误而不是统一提示
接口层应该统一错误“形状”,例如 code、message、status,但不要在拦截器里直接弹 Toast 或执行页面跳转。否则后台轮询、静默刷新、表单提交都会被同一副作用绑死,测试也更困难。
业务层拿到 AppError 后可以按场景决定行为:表单显示字段错误,列表页显示重试按钮,鉴权失效再由专门的会话模块处理。这样“错误如何描述”与“页面如何响应”保持解耦。
处理令牌刷新的边界
如果响应为 401 后需要刷新令牌,应增加“单次刷新 + 等待队列”机制,避免多个并发请求同时触发刷新。刷新接口本身还应跳过普通鉴权拦截,否则可能形成递归请求。
稳定的接口层不是把所有逻辑塞进拦截器,而是让拦截器只承担跨请求的横切职责,再用类型化包装器把响应结构收口。这样令牌、追踪、错误和数据类型都集中,又不会牺牲业务层的可控性。