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 项目后即可使用。

ts
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
}

预期结果

text
成功且 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,也不要再次判断业务码。下面是调用方式;错误先交给下一层统一处理,本课只验证成功出口。

ts
interface User {
  id: number
  name: string
}

const users = await request<User[]>({
  method: 'GET',
  url: '/users'
})

console.log(users[0]?.name)

预期输出

text
Alice

接口真实数据可能不同,但 users 的类型始终是 User[],而不是 Axios 响应对象。

关键边界

不要在成功拦截器里吞掉格式异常。如果后端偶尔返回非统一结构,应把它视为 PROTOCOL 契约错误并明确失败,而不是返回 undefined。同时,不要直接把服务端堆栈、SQL 信息或原始响应体写进 ApiError.message;调试字段可进入受控日志,页面只使用经过筛选的信息。

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

目录与阅读设置

阅读设置

17

记录一个想法

封装响应拦截器

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

登录哪都通