[!info] related notes

• 所属 MOC: HTTP 与前端网络请求
• 上位概念: Axios
• 前置概念: Axios 实例, Axios 拦截器, Axios 错误模型
• 相关实践: Axios 封装实践, 封装一个优雅的axios

Axios 封装模式

主题范围

这篇只讲“怎么把 Axios 包成一个稳定的业务层客户端”，不重复讲 API 本身。

一句话结论

推荐分层：实例 -> 拦截器 -> 错误归一化 -> 业务 API 模块。

核心结构

axios.create()
  -> request interceptors
  -> response interceptors
  -> error normalization
  -> domain api functions

常见封装目标

• 统一 baseURL 和 timeout
• 自动注入 token
• 统一处理 401 / 403 / 5xx
• 统一抽取 data
• 统一取消与重试策略

两种常见返回风格

• Promise<T> + try/catch
• Promise<Result<T>> + 显式判断

返回契约与边界

Result 应使用判别联合：成功分支带 data，失败分支带必需的 error。它让分支处理可检查，但不会强迫调用方消费结果，也不能靠 get<T>() 自动验证网络数据。

区分 HTTP 状态、业务信封、取消与结果未知。不要同时在拦截器和 API 模块重复剥离 data；响应结构改变时，类型与调用方必须同步。

带 token 的客户端要限制请求目标，baseURL 不是白名单。401 刷新采用有界的共享刷新任务，成功与失败都要结束等待者；每个重放请求都要限制刷新次数，已取消请求不应复活。刷新请求需避开自身刷新拦截链。通用重试与副作用判断见 Retry Policy。

项目实例见 Axios 封装实践，其中历史设计和当前源码观察分开记录，不把项目局部实现当通用保证。

最短记忆方式

• 先实例化
• 再拦截
• 再归一化错误
• 最后暴露业务 API