Vue / 系统课时

请求与响应拦截

请求与响应拦截

接口层如果让每个业务函数自行拼令牌、追踪标识、判断错误码和解包数据,很快会出现重复逻辑与返回类型不一致。本课用 Axios 实例建立统一管线,让横切逻辑集中,同时保留清晰的 TypeScript 类型边界。

学习目标

  • 用请求拦截器统一注入认证令牌与追踪标识
  • 用响应拦截器归一化 HTTP 错误和业务错误
  • 用类型化请求包装器完成响应解包,避免运行时结果与静态类型不一致

划清拦截器的职责

请求拦截器适合处理“每次请求都要做”的事情,例如追加 Authorization、生成 X-Trace-Id、补充语言或租户信息。响应拦截器适合把 HTTP 失败和业务失败转换成统一错误,让页面不必理解 Axios 的错误结构。

响应解包要特别注意类型。直接在响应拦截器里把 AxiosResponse<T> 替换成裸 T,运行时虽然方便,却会让 Axios 原有类型声明与真实返回值脱节。更稳妥的做法是:拦截器负责校验与归一化,薄包装器 request<T>() 再集中返回 data。

请求与响应拦截管线

建立类型化请求管线

下面示例使用自定义 adapter 模拟服务端,因此不依赖真实接口;在已安装 Axios 的 TypeScript 项目中可直接运行。请求拦截器只修改配置,响应拦截器只判断失败,request<T> 负责把统一响应结构解包为业务类型。

ts
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);

预期输出

text
authorization attached: true
trace attached: true
user: 7 Ada

示例中的追踪 ID 实际值每次都不同,因此验证重点是请求头已被注入,而不是固定某个 <ID>。

统一错误而不是统一提示

接口层应该统一错误“形状”,例如 code、message、status,但不要在拦截器里直接弹 Toast 或执行页面跳转。否则后台轮询、静默刷新、表单提交都会被同一副作用绑死,测试也更困难。

业务层拿到 AppError 后可以按场景决定行为:表单显示字段错误,列表页显示重试按钮,鉴权失效再由专门的会话模块处理。这样“错误如何描述”与“页面如何响应”保持解耦。

处理令牌刷新的边界

如果响应为 401 后需要刷新令牌,应增加“单次刷新 + 等待队列”机制,避免多个并发请求同时触发刷新。刷新接口本身还应跳过普通鉴权拦截,否则可能形成递归请求。

稳定的接口层不是把所有逻辑塞进拦截器,而是让拦截器只承担跨请求的横切职责,再用类型化包装器把响应结构收口。这样令牌、追踪、错误和数据类型都集中,又不会牺牲业务层的可控性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

请求与响应拦截

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通