模块一:基础配置与物理隔离(config.ts & client.ts)
☑ 多环境切换:通过 import.meta.env 读取 VITE_BASE_URL 等,解决 IP 写死问题。
☑ 超时安全兜底:利用 Nuber.isFinite 防止 NaN 或负数,默认 15s。
☑ 跨域凭证精准控制:通过 toLowerCase() === 'true' 严格判断,防止字符串 "false" 导致的 CORS 灾难。
☑ 工厂模式实例隔离:导出 createHttpClient,避免全局污染,支持按需生成新实例。
☑ GET 数组序列化:配置 paramsSerializer: { indexes: null },解决 ids[]=1 后端不认的问题(对应你提供的第四章)。
☑ 全局依赖注入:切换底层与 Vue/Pinia/Router 的强耦合。
模块二:契约与类型图纸(types.ts & dependencies.ts)
☑ 严格的类型约束:HttpConfig 继承原生类型并扩展 skipToken 等。
☑ 兼容性洋葱图纸:BaseResponse<T> 允许 success 为 boolean | string,允许 data 为空。
☑ 标准错误对象:HttpError 包含 kind(网络/超时/业务等)、code、raw。
☑ 全能依赖插排:HttpDependencies 包含 getToken、onUnauthorized(401处理)、showMessage(UI提示)、reportError(监控上报)、showLoading/hideLoading、getExtraHeaders(额外头)。
模块三:请求拦截与防呆(interceptors/request.ts)
☑ 动态 Token 注入:从插排中获取 Token,支持 skipToken 白名单跳过。
☑ 防重复拼接:正则检测 Bearer 前缀,防止变成 Bearer Bearer xxx。
☑ 防竞态(AbortController):配合业务层,在新请求发起时掐断旧请求,静默处理 CanceledError。
模块四:响应安检与错误治理(interceptors/response.ts)
☑ 9步漏斗式短路:优先级从高到底,精准拦截。
- 取消请求:静默处理,不弹窗。
- 网络断层/超时:无 response,直接报网络错误。
- 500 系统级崩溃:绝对不读后端 body,封杀 SQL 泄漏,直接返回前端写死的“系统繁忙”。
- 401 连环踢:触发
onUnauthorized,加状态锁,防止跳 5 次登录页。 - 其他 HTTP 异常:查字典返回标准文案。
- Blob 流放行:判断
responseType === 'blob'时直接返回原始 response,防止文件乱码。
☑ 契约码表与未知码拦截:业务成功放行;业务失败查码表;查不到码表则报 COMMON.UNKNOWN 并上报工单,绝不信任后端原话。
☑ 探针脱敏(sanitize.ts):针对老接口的脏数据(HTML、SQL、堆栈、超长文本)进行特征检测与整条替换,只报监控不展示给用户。
模块五:门面容错(index.ts & helpers/retry.ts)
☑ 门面模式剥洋葱:业务层直接调用 api.get / api.post,底层统一 return response.data.data as T,业务层不再写 res.data.data。
☑ 弱网自动重试:通过 retryRequest 包装器,仅对 GET 或特定状态码(502/504/纯断网)静默重试。
☑ 延迟防雪崩:重试前 await delay(1000),防止把后端打死。
☑ 并发弹窗防抖:全局维护时间锁,多个接口同时报错只弹一次提示。