如果你在 GitHub 或某个技术群里看到“ax”这个项目名第一反应大概率是 axios 的简称。我当初起这个名字也确实是想做一个类似 axios 但更轻、更贴自己项目的 HTTP 请求工具。现在很多团队已经离不开 axios、umi-request 这类库但在实际接手项目时会发现下载一个几 MB 的依赖最终用到的只有 get/post/拦截器这几个能力剩下的大堆功能都是给别的场景准备的。于是我用一个周末写了一个叫 ax 的请求库核心就是解决“我自己项目里那点请求需求”顺便把请求原理彻底理清楚。干前端这几年我越来越发现一件事请求层是每个项目都跑不掉的基础设施但也是最容易被低估的部分。很多人觉得“不就是调一下 axios.get 嘛”等到要统一处理登录态失效、要做接口耗时统计、要自动重试、要取消上一次未完成的请求时才发现要么在业务代码里到处塞补丁要么被库的自带行为坑一把。所以我想干脆从零写一个属于自己的 ax把请求相关的能力都收拢到一个文件里想加什么逻辑自己加出了问题也知道去哪改。1. 为什么我会动手写 ax 这个东西1.1 标题里的 ax 到底代表什么ax 不是某个开源大项目的名字它是我给自己封装的一个轻量级 HTTP 请求库起的代号。网上搜 ax多半会跳出来 Victory Axe 游戏、AX 通信协议或者各种咨询公司缩写但在前端工程师眼里第一反应往往是 axios 的简称。事实也是这样我写 ax 的初衷就是想做一个去掉冗余功能、只保留核心链路、同时底层实现完全可控的请求工具用来替代业务代码里那些“用着用着就想骂人”的重复网络请求逻辑。后来真正动手之后我才发现 ax 这个代号还挺合适的a 代表 applicationx 代表 crossing意思是“跨应用的请求通道”。虽然这层解释是后来硬凑的但恰好描述了这个库的定位——不绑定任何框架不依赖任何运行时就是一个纯粹的请求基础设施。1.2 它到底解决什么问题适合谁参考ax 解决的三个核心问题是请求配置太分散、错误处理不统一、生命周期行为不透明。用它将 baseURL、超时时间、拦截器、错误码映射集中管理后业务组件里只需要写ax.get(/user/info)这样一行剩下的事情全部交给请求层。遇到登录过期响应拦截器统一跳转遇到重复请求在 request 拦截器里就能用 AbortController 取消掉上一个未完成的请求。如果你是刚学前端不久、想搞明白网络请求底层原理的同学这篇文章可以直接当源码阅读笔记看。如果是有两三年经验、天天在项目里封装 axios 的工程师那 ax 的设计思路和踩坑过程大概率能帮你补上几个平时没注意到的细节。我不打算把它包装成什么重量级框架它就是一个小而实用的工具库关键是把请求这条链路上的每个决策点讲透。2. ax 的整体设计与方案选型2.1 对外 API 怎么定一张设计稿看清全貌动手编码之前我先把 ax 的对外接口画了出来。这不是一个可选的规划步骤而是真正帮我少走弯路的关键。我的要求是ax 的调用方式要让用过 axios 的人零成本上手但内部实现又不能被 axios 的包袱绑死。import { Ax, CancelToken } from ./ax; const defaultConfig { baseURL: /api, timeout: 10000, headers: { Content-Type: application/json } }; const ax new Ax(defaultConfig); // 最基础的用法 const res await ax.get(/user/info, { params: { id: 1 } }); const data await ax.post(/user/save, { name: 张三 }); // 拦截器请求发出前做点什么回来后再做点什么 ax.interceptors.request.use(config { const token getToken(); config.headers.Authorization Bearer ${token}; return config; }); ax.interceptors.response.use( response { if (response.data.code ! 0) { return Promise.reject(new Error(response.data.message)); } return response.data.data; }, error { if (error.response?.status 401) redirectToLogin(); return Promise.reject(error); } ); // 如果需要取消请求 const controller new CancelToken(); ax.get(/slow/api, { cancelToken: controller.token }).catch(e { if (ax.isCancel(e)) console.log(请求被取消); }); controller.cancel(手动取消);设计完这个接口我心里基本有数了核心只有五个部分请求主流程、拦截器管理、默认配置合并、取消令牌、错误分类。没有乱七八糟的插件机制和额外适配器体系所有逻辑维持在一个能一眼看完的量级。事实证明这个克制的 API 设计让后面的实现和维护都非常轻松。2.2 底层用 XMLHttpRequest 还是 fetch别急着跟风这是 ax 里的第一个关键决策点。我最终实现了两个适配器默认走 XMLHttpRequest但把 fetch 适配器也留了出来。为什么这么选fetch 虽然原生支持 Promise、支持流式读取但有两个在实际业务里特别烦的限制一是对请求超时的控制需要自己借助 AbortController 或者 Promise.race 去模拟而 XHR 原生就有 timeout 事件二是 fetch 在 HTTP 状态码为 400/500 时并不会把响应抛给 .catch它依然会走 resolve只是 response.ok 是 false这意味着你要自己多写一层状态码判断逻辑。XHR 的缺点同样存在比如事件模型比较老、参数格式繁琐、对 Promise 不友好但这些都能在适配器内部消化掉。我更看重 XHR 的这几个能力超时事件明确、上传进度事件完善、错误信息里能带上 status 详情。另外在示例项目和旧系统兼容上XHR 的支持面也明显更广。这不是说 fetch 不好而是在大多数中后台项目的实际场景里XHR 更省事。如果你的目标环境非常现代且主要做流式响应那直接把默认适配器换成 fetch 版就好ax 的对外接口不用动。2.3 模块怎么划分既不过度设计也不揉成一团我见过很多“十几行代码干完一件事”的库也见过为了两个函数拆了十二个文件夹的库两种我都吃过亏。给 ax 划分模块我的原则是一个模块只承担一种职责但模块总数控制在六个以内。src/ ├── index.js # 对外入口导出 Ax 类和辅助方法 ├── core.js # 请求主流程配置合并、拦截器编排、发起请求 ├── cancel.js # CancelToken 取消令牌实现 ├── adapter/xhr.js # XHR 适配器 ├── adapter/fetch.js # fetch 适配器 └── utils.js # 工具函数URL 拼接、参数序列化、键值合并这个结构的好处很明显核心逻辑在 core.js 里一口气能读完想调试请求流程不用跨文件跳转适配器和核心解耦以后想再加一个基于 Node http 模块的适配器也不需要动 core 的一行代码。取消令牌单独放是因为它的状态流转独立于请求流程而且需要在多个实例复用时保证状态隔离。工具函数不追求完备只放真正会用的两三个方法避免整个项目被一堆用不到的公共函数撑起来。3. ax 的核心代码实现细节3.1 请求主流程从参数合并到网络发起ax 的请求过程可以分成三个大阶段合并配置、执行拦截器链、交给适配器发起。合并配置是整个流程的地基所有后续行为都依赖于这一步产出的完整 config 对象。// core.js 核心片段 async request(config) { const mergedConfig { ...this.defaults, ...config, headers: { ...(this.defaults.headers || {}), ...(config.headers || {}) } }; let promise Promise.resolve(mergedConfig); const reqInterceptors this.interceptors.request.handlers; const resInterceptors this.interceptors.response.handlers; // 把所有请求拦截器放到 dispatchRequest 前面 const chain [this.dispatchRequest, undefined]; reqInterceptors.forEach(interceptor { chain.unshift(interceptor.fulfilled, interceptor.rejected); }); while (chain.length) { promise promise.then(chain.shift(), chain.shift()); } // 响应拦截器按添加顺序依次包裹 resInterceptors.forEach(interceptor { promise promise.then(interceptor.fulfilled, interceptor.rejected); }); return promise; }注意这段拦截器链的实现没有用 async/await 去写循环而是用一个静态 chain 数组配合 Promise.then 来串接。这样做的原因是拦截器本质上是函数序列顺序有严格要求请求拦截器按添加顺序正着执行响应拦截器按“装饰器”的方式依次包在外面。你可以在拦截器里写任意多个方法它们在请求前后各自形成一个队列这种组合方式比简单的 if 嵌套要清晰得多而且天然支持异步操作——比如在 request 拦截器里刷新 token只要返回的 Promise 在刷新完成后 resolve 即可。接下来是 dispatchRequest 的核心动作把合并后的 config 交给适配器然后对响应做初步包装。async dispatchRequest(config) { const url buildURL(config.baseURL, config.url, config.params); const response await httpAdapter({ ...config, url }); return { status: response.status, statusText: response.statusText, data: response.data, headers: response.headers, config }; }为什么 dispatchRequest 不直接返回业务数据而是包一层 response 对象因为响应拦截器里可能有多种场景想拿到完整响应比如 201 状态时要读取 location 头、文件上传完成时要拿进度百分比。如果直接把数据裸露出去这些信息就丢了。包装成一个标准对象后响应拦截器既可以处理业务数据也可以根据 status 做链路分支。3.2 拦截器机制用队列实现请求前后的统一切口拦截器是 ax 里业务接入面最广的部分几乎人人都会用但很多人没想过它内部怎么把请求前的逻辑放到请求前面。上节代码里我用 chain.unshift 把 request 拦截器插入到调用链前方这里是拦截器管理器的完整实现。// interceptors.js class InterceptorManager { constructor() { this.handlers []; } use(fulfilled, rejected) { this.handlers.push({ fulfilled, rejected }); return this.handlers.length - 1; } eject(id) { if (this.handlers[id]) { this.handlers[id] null; } } forEach(fn) { this.handlers.forEach(h { if (h ! null) fn(h); }); } }拦截器整体是一个 Promise 链。核心顺序是请求拦截器按 use 的先后顺序从外到里执行响应拦截器按 use 的先后顺序从里到外执行。也就是说后添加的请求拦截器更加贴近网络请求后添加的响应拦截器则更接近业务侧。很多开发者把请求拦截器当成“配置加工器”、把响应拦截器当成“数据解包器”这是最常见的用法。但如果你想在响应拦截器里做日志上报要注意顺序后加的响应拦截器会先拿到数据便于在数据流出 ax 之前截获。我特别想提醒一个易错点拦截器里必须 return config 或 Promise 链上的值。如果你在 request 拦截器里只修改了 config 却没有 return那下一个环节拿到的是 undefined请求会静默失败且很难排查。我在接业务时踩过一次当时加了打印日志都看不到请求发出排查了快半小时才发现是某个拦截器少了 return。这个坑我在后面问题清单里还会再提到因为它的隐蔽程度真的很高。3.3 超时控制与请求取消两个机制要分清超时和取消这两个能力在 XHR 适配器里是两套写法但它们的核心思路其实相通都要拿到一个外部可以随时叫停的句柄。对 XHR 来说超时用xhr.timeout ontimeout取消用xhr.abort对 fetch 来说两者都靠 AbortController。// adapter/xhr.js export default function xhrAdapter(config) { return new Promise((resolve, reject) { const xhr new XMLHttpRequest(); const method config.method.toUpperCase(); const url config.url; xhr.open(method, url); Object.keys(config.headers).forEach(key { if (config.headers[key] ! undefined) { xhr.setRequestHeader(key, config.headers[key]); } }); if (config.timeout) { xhr.timeout config.timeout; xhr.ontimeout () { reject(createError(timeout, config, ECONNABORTED)); }; } if (config.cancelToken) { config.cancelToken.promise.then(cancel { if (!xhr.aborted) { xhr.aborted true; xhr.abort(); reject(cancel); } }); } xhr.onerror () { reject(createError(network error, config, ERR_NETWORK)); }; xhr.onreadystatechange function () { if (xhr.readyState ! 4) return; const status xhr.status; if (status 0) return; const response { data: parseResponse(xhr.responseText, config.responseType), status, statusText: xhr.statusText, headers: parseHeaders(xhr.getAllResponseHeaders()), config }; if (status 200 status 300) { resolve(response); } else { reject(createError(request failed, config, mapStatusToErrorCode(status), response)); } }; xhr.send(config.data); }); }这里有几个细节值得单独说。第一xhr.ontimeout触发后 Promise 会被 reject但浏览器层面的 XHR 其实已经自己中止了不需要再手动调 abort否则可能触发 onabort 导致二次 reject。第二对于取消令牌的监听我用config.cancelToken.promise.then(...)这个 promise 一执行 cancel对应的 XHR 立刻 abort 并 reject但如果请求已经完成就不能再搅和了所以用xhr.aborted这个标志位挡住。第三状态码 0 的情况一般出现在请求被取消或混合内容拦截没必要当作正常响应解析直接 return 就行。3.4 响应处理与错误分类让业务侧从 if 地狱里解放出来请求发出去了回包到达后ax 要做三件事判断状态码是否在 2xx 范围、把 responseText 解析成合适的数据结构、把错误按照类型打上标签。我定义了一套精简的错误码覆盖了日常项目绝大部分场景。错误码含义典型场景ECONNABORTED请求超时被中止接口 10s 未返回ERR_NETWORK网络层错误断网、DNS 解析失败ERR_CANCELED主动取消组件卸载时取消请求ERR_BAD_REQUEST4xx 请求错误参数校验失败、未授权ERR_BAD_RESPONSE5xx 服务端错误后端服务挂了、网关 502错误分类的价值不在于给人看而在于让业务代码能精确拦截。比如全局错误提示里对 ERR_CANCELED 应该静默因为它通常是路由切换导致的副作用对 ERR_BAD_RESPONSE 可以弹一个“服务暂时不可用”对 ECONNABORTED 则提示检查网络。如果没有统一的错误码业务那边只能去读 error.message 字符串既不稳定也没法做分支处理。4. 把 ax 接入真实项目从封装到落地4.1 在业务代码里怎么封装才能让组件更干净很多项目把 axios 直接用然后每个页面自己写 try/catch 和 loading最终代码里到处是重复的错误提示。用 ax 之后我的习惯是再包一层 request 实例让业务侧只关心数据和语义化异常。// src/api/request.js import { Ax } from ./ax; const service new Ax({ baseURL: import.meta.env.VITE_API_BASE_URL || /api, timeout: 8000, headers: { Content-Type: application/json } }); service.interceptors.request.use(config { const token store.getToken(); if (token) { config.headers.Authorization Bearer ${token}; } return config; }); service.interceptors.response.use( response { const entity response.data; if (entity.code ! 0) { const err new Error(entity.message); err.bizCode entity.code; return Promise.reject(err); } return entity.data; }, error { if (error.code error.code.startsWith(ERR_)) { return Promise.reject(error); } const status error.response?.status; switch (status) { case 401: redirectToLogin(); break; case 403: showMessage(没有权限); break; case 500: showMessage(服务器开小差了); break; default: showMessage(error.message || 请求失败); } return Promise.reject(error); } ); export function get(url, params, config {}) { return service.get(url, { ...config, params }); } export function post(url, data, config {}) { return service.post(url, data, config); } export default service;这样封装之后组件里的请求就变成const data await get(/user/info, { id: userId }); setInfo(data);我不再需要每个请求里写 try/catch 去处理 401也不需要每个页面重复写 loading 状态。loading 可以通过拦截器计数器统一处理也可以交给 useRequest 这种 hook。特别建议把 get/post 再包成具名函数这样 IDE 搜索请求的引用位置会非常快排查问题效率很高也方便后续在函数内部做参数默认值、埋点上报等扩展。4.2 和现有技术栈的搭配React、Vue、小程序都能用ax 是纯 JavaScript 的请求层不绑定任何框架所以接入 React 和 Vue 都很直接。以 Vue 为例我一般会在 main.js 里把封装好的 service 挂到 provide 上这样页面里通过inject($ax)就能拿到实例不需要每个组件顶部重复 import。React 的话我更推荐直接用 hooks 封装比如下面这个简化版 useAxiosfunction useAxios(url, options {}) { const [data, setData] useState(null); const [loading, setLoading] useState(false); const [error, setError] useState(null); const controllerRef useRef(new CancelToken()); useEffect(() { const controller new CancelToken(); const fetchData async () { setLoading(true); try { const result await service.get(url, { ...options, cancelToken: controller.token }); setData(result); } catch (e) { if (service.isCancel(e)) { return; } setError(e); } finally { setLoading(false); } }; fetchData(); return () controller.cancel(); }, [url]); return { data, loading, error }; }这里 hook 的 cleanup 里调controller.cancel()是防止组件卸载之后还收到过期响应。很多前端项目重复渲染导致的竞态基本都是少了这一步。如果你的请求不涉及组件销毁场景那也可以不做取消但在列表页、详情页这种高频率路由切换的页面建议还是加上否则可能出现 A 页面的接口响应把 B 页面的状态覆盖掉的诡异问题。小程序环境如 Taro、uni-app用的是内置 request API没法直接复用 ax 的 XHR 适配器但拦截器部分可以完整保留。你只需要把 dispatchRequest 里的 httpAdapter 替换成小程序封装好的 request 函数即可ax 的核心价值依然存在。这说明适配器拆分的价值不只在于代码整洁它直接决定了这个工具的可移植范围。4.3 TypeScript 类型标注让调用方少踩坑ax 的核心代码是用 JS 写的但对外类型声明我用 TypeScript 补全了否则在 TS 项目里用 ax 会一路 any体验太差。类型定义的重点是 config、response、error 三类对象。export interface AxRequestConfig { url?: string; baseURL?: string; method?: get | post | put | delete | patch; params?: Recordstring, any; data?: any; headers?: Recordstring, string; timeout?: number; responseType?: XMLHttpRequestResponseType; cancelToken?: CancelToken; } export interface AxResponseT any { data: T; status: number; statusText: string; headers: Recordstring, string; config: AxRequestConfig; } export interface AxErrorT any extends Error { code?: string; config: AxRequestConfig; response?: AxResponseT; }写类型声明时有个小技巧getT返回PromiseT这个 T 指的是响应拦截器剥壳之后的业务数据类型而不是 AxResponse。因为我们在拦截器里已经把数据萃取出来了调用方期望拿到的自然是业务数据。如果你把返回类型写成PromiseAxResponseT那每个调用点都得再剥一层非常别扭。类型设计要跟着实际运行时的数据形态走否则“看似完善”的类型声明反而会误导人。5. 从零到上线ax 落地过程中的典型问题与排查笔记5.1 超时了但请求还在跑是怎么回事我在用 ax 的第一个真实项目里就撞上了这个问题设置了 timeout 8000网络很慢时确实在 8 秒后收到了超时报错但浏览器的 Network 面板里请求依然处于 pending 状态后端日志里也看到这个请求最后被处理了。为什么超时 reject 了请求却还在跑原因在于 XHR 的超时只是“前端不等待响应了”并不是真的把服务端请求撤回来。终止请求取决于浏览器行为在部分浏览器中xhr.timeout到达后会自动 abort但如果后端已经长时间不返回TCP 连接并不会被立刻回收表现就是请求还挂在网络面板里。处理思路有两个一是超时后如果服务端其实已经处理完前端只是不想继续等待那超时错误是合理的二是如果需要更严格的“请求终止”要靠取消令牌触发xhr.abort()这样浏览器会立即断开连接。所以 ax 的超时和取消是两个独立机制超时管“我不等了”取消管“我强制掐断”业务上要区分开。5.2 拦截器里改了 config但请求发出去还是没有变更这个问题的根源几乎都是在 request 拦截器里修改了 config 中某个字段但 dispatchRequest 用的却是另一个对象。比如你以为直接改了 config.url实际上 URL 拼接逻辑用的是buildURL(config.baseURL, config.url, config.params)的结果而不是 config.url 本身。如果你在拦截器里改的是 params要记得用新值重新走 buildURL否则拼出来的地址还是旧的。另外还有一种常见情况拦截器里手动写了config.headers[X-Custom] abc但 headers 在合并配置时可能被后续的默认头覆盖。因为合并阶段我采用的是浅拷贝合并如果某个 key 在默认配置里已经存在拦截器里的赋值会被覆盖得无声无息。要避免这种情况最好的办法是拦截器全部执行完后再做 header 合并或者在拦截器里显式写成config.headers { ...config.headers, X-Custom: abc }把合并路径交给新对象。排查这类问题时我一般会在 dispatchRequest 的第一行打印 config对比哪一层丢了字段。5.3 取消请求之后Promise 竟然走进 then 而不是 catch这个坑来自取消令牌和响应状态判断的先后顺序。我在最初的实现里cancelToken 的 promise 一旦 resolve就直接xhr.abort()但 onreadystatechange 里如果对 readyState ! 4 的包直接 return理论上不会产生新的 resolve。不过如果你在 abort 之前已经把 readyState 变为 4比如服务端响应非常快数据已经回来了abort 之后再检查 status 时就会被代码命中走 resolve 分支。我的修复方案是引入一个 aborted 标志位一旦取消就把xhr.aborted置为 true然后在 onreadystatechange 里判断如果xhr.aborted就直接 reject 取消错误不再走正常状态判断。这个标志位既防止了状态竞争也避免了重复 reject 导致 Promise 状态被覆盖。使用取消令牌时的原则是取消之后所有后续回调都不应再触发 resolve宁可多打一个日志也不要让数据流被切断后还继续流动。5.4 并发请求多时要不要加请求合并或缓存做管理后台的时候同一个字典接口在页面初始化时会被五六个组件同时调用后端接口设计又不支持批量查询于是每个组件都发了一次请求。这种场景我用 ax 做了两个层面的优化请求合并和结果缓存。请求合并思路是在短时间内如果多个请求的 url 完全相同就只发一个请求让所有调用方共享同一个 Promise。实现上可以在 dispatchRequest 里维护一个 Mapconst pendingMap new Map(); async function dispatchWithMerge(config) { const key ${config.method}-${config.url}-${JSON.stringify(config.params || {})}; if (pendingMap.has(key)) { return pendingMap.get(key); } const p httpAdapter(config).finally(() { pendingMap.delete(key); }); pendingMap.set(key, p); return p; }结果缓存则适用于字典类稳定数据首次请求成功后把数据存到模块级 Map 里后续直接返回缓存值同时提供一个 forceRefresh 参数绕过缓存。这两个优化看起来不复杂但对接口压力非常大的中后台页面来说收益很实在也体现了自研请求库的灵活性——如果你用别人的库加这种自定义能力会比较绕。当然请求合并也有坑比如不同页面带不同的 token合并后可能共享了不该共享的凭证所以合并键里务必把鉴权头也拼进去。6. ax 写成之后我沉淀下的几点体会ax 从设计到落地用了大概三天其中半天写核心一天半补适配器和拦截器剩下半天在项目里接入并解决上面几个问题。这段经历给我最大的感受是请求库根本不是“写个 get 方法”那么简单真正难的是把超时、取消、拦截器顺序、错误分类、类型推导这些边界行为想清楚。任何一个环节处理不好上线后都会以各种诡异的形式冒出来比如页面偶尔白屏、接口重复请求、401 提示弹不够。如果你也想动手写一个自己的 ax我的建议是不要一步到位先实现一个最基础的单文件版本满足你当前项目的 80% 需求再逐步把拦截器、取消、适配器拆分出来。每加一个能力都要反问自己这个能力是给我的业务用的还是为了显得很完整功能膨胀是自研库最容易犯的错保持克制的收益比多写两个炫技方法大得多。另外一个很实用的技巧把 ax 的源码直接放在自己项目里而不是打成 npm 包再引回来。因为请求层会跟着业务演化比如增加公司统一的埋点 header、根据环境切换 baseURL这些逻辑放在源码仓库里可以直接改、直接看 diff比依赖一个“黑盒 npm 包”要踏实得多。等哪天你真的做了一套通用配置再抽成独立包也不迟。最后分享一个小经验写请求库或者任何底层工具时务必给自己留一个 debug 模式。ax 里我加了一个开启后打印完整 config、拦截器执行顺序、适配器输出日志的方法排查线上问题时就靠它快速定位是配置问题还是网络问题。这个功能本身不过几行代码但它能在你最焦头烂额的时候帮你省下一整晚的排查时间。
如果你在 GitHub 或某个技术群里看到“ax”这个项目名第一反应大概率是 axios 的简称。我当初起这个名字也确实是想做一个类似 axios 但更轻、更贴自己项目的 HTTP 请求工具。现在很多团队已经离不开 axios、umi-request 这类库但在实际接手项目时会发现下载一个几 MB 的依赖最终用到的只有 get/post/拦截器这几个能力剩下的大堆功能都是给别的场景准备的。于是我用一个周末写了一个叫 ax 的请求库核心就是解决“我自己项目里那点请求需求”顺便把请求原理彻底理清楚。干前端这几年我越来越发现一件事请求层是每个项目都跑不掉的基础设施但也是最容易被低估的部分。很多人觉得“不就是调一下 axios.get 嘛”等到要统一处理登录态失效、要做接口耗时统计、要自动重试、要取消上一次未完成的请求时才发现要么在业务代码里到处塞补丁要么被库的自带行为坑一把。所以我想干脆从零写一个属于自己的 ax把请求相关的能力都收拢到一个文件里想加什么逻辑自己加出了问题也知道去哪改。1. 为什么我会动手写 ax 这个东西1.1 标题里的 ax 到底代表什么ax 不是某个开源大项目的名字它是我给自己封装的一个轻量级 HTTP 请求库起的代号。网上搜 ax多半会跳出来 Victory Axe 游戏、AX 通信协议或者各种咨询公司缩写但在前端工程师眼里第一反应往往是 axios 的简称。事实也是这样我写 ax 的初衷就是想做一个去掉冗余功能、只保留核心链路、同时底层实现完全可控的请求工具用来替代业务代码里那些“用着用着就想骂人”的重复网络请求逻辑。后来真正动手之后我才发现 ax 这个代号还挺合适的a 代表 applicationx 代表 crossing意思是“跨应用的请求通道”。虽然这层解释是后来硬凑的但恰好描述了这个库的定位——不绑定任何框架不依赖任何运行时就是一个纯粹的请求基础设施。1.2 它到底解决什么问题适合谁参考ax 解决的三个核心问题是请求配置太分散、错误处理不统一、生命周期行为不透明。用它将 baseURL、超时时间、拦截器、错误码映射集中管理后业务组件里只需要写ax.get(/user/info)这样一行剩下的事情全部交给请求层。遇到登录过期响应拦截器统一跳转遇到重复请求在 request 拦截器里就能用 AbortController 取消掉上一个未完成的请求。如果你是刚学前端不久、想搞明白网络请求底层原理的同学这篇文章可以直接当源码阅读笔记看。如果是有两三年经验、天天在项目里封装 axios 的工程师那 ax 的设计思路和踩坑过程大概率能帮你补上几个平时没注意到的细节。我不打算把它包装成什么重量级框架它就是一个小而实用的工具库关键是把请求这条链路上的每个决策点讲透。2. ax 的整体设计与方案选型2.1 对外 API 怎么定一张设计稿看清全貌动手编码之前我先把 ax 的对外接口画了出来。这不是一个可选的规划步骤而是真正帮我少走弯路的关键。我的要求是ax 的调用方式要让用过 axios 的人零成本上手但内部实现又不能被 axios 的包袱绑死。import { Ax, CancelToken } from ./ax; const defaultConfig { baseURL: /api, timeout: 10000, headers: { Content-Type: application/json } }; const ax new Ax(defaultConfig); // 最基础的用法 const res await ax.get(/user/info, { params: { id: 1 } }); const data await ax.post(/user/save, { name: 张三 }); // 拦截器请求发出前做点什么回来后再做点什么 ax.interceptors.request.use(config { const token getToken(); config.headers.Authorization Bearer ${token}; return config; }); ax.interceptors.response.use( response { if (response.data.code ! 0) { return Promise.reject(new Error(response.data.message)); } return response.data.data; }, error { if (error.response?.status 401) redirectToLogin(); return Promise.reject(error); } ); // 如果需要取消请求 const controller new CancelToken(); ax.get(/slow/api, { cancelToken: controller.token }).catch(e { if (ax.isCancel(e)) console.log(请求被取消); }); controller.cancel(手动取消);设计完这个接口我心里基本有数了核心只有五个部分请求主流程、拦截器管理、默认配置合并、取消令牌、错误分类。没有乱七八糟的插件机制和额外适配器体系所有逻辑维持在一个能一眼看完的量级。事实证明这个克制的 API 设计让后面的实现和维护都非常轻松。2.2 底层用 XMLHttpRequest 还是 fetch别急着跟风这是 ax 里的第一个关键决策点。我最终实现了两个适配器默认走 XMLHttpRequest但把 fetch 适配器也留了出来。为什么这么选fetch 虽然原生支持 Promise、支持流式读取但有两个在实际业务里特别烦的限制一是对请求超时的控制需要自己借助 AbortController 或者 Promise.race 去模拟而 XHR 原生就有 timeout 事件二是 fetch 在 HTTP 状态码为 400/500 时并不会把响应抛给 .catch它依然会走 resolve只是 response.ok 是 false这意味着你要自己多写一层状态码判断逻辑。XHR 的缺点同样存在比如事件模型比较老、参数格式繁琐、对 Promise 不友好但这些都能在适配器内部消化掉。我更看重 XHR 的这几个能力超时事件明确、上传进度事件完善、错误信息里能带上 status 详情。另外在示例项目和旧系统兼容上XHR 的支持面也明显更广。这不是说 fetch 不好而是在大多数中后台项目的实际场景里XHR 更省事。如果你的目标环境非常现代且主要做流式响应那直接把默认适配器换成 fetch 版就好ax 的对外接口不用动。2.3 模块怎么划分既不过度设计也不揉成一团我见过很多“十几行代码干完一件事”的库也见过为了两个函数拆了十二个文件夹的库两种我都吃过亏。给 ax 划分模块我的原则是一个模块只承担一种职责但模块总数控制在六个以内。src/ ├── index.js # 对外入口导出 Ax 类和辅助方法 ├── core.js # 请求主流程配置合并、拦截器编排、发起请求 ├── cancel.js # CancelToken 取消令牌实现 ├── adapter/xhr.js # XHR 适配器 ├── adapter/fetch.js # fetch 适配器 └── utils.js # 工具函数URL 拼接、参数序列化、键值合并这个结构的好处很明显核心逻辑在 core.js 里一口气能读完想调试请求流程不用跨文件跳转适配器和核心解耦以后想再加一个基于 Node http 模块的适配器也不需要动 core 的一行代码。取消令牌单独放是因为它的状态流转独立于请求流程而且需要在多个实例复用时保证状态隔离。工具函数不追求完备只放真正会用的两三个方法避免整个项目被一堆用不到的公共函数撑起来。3. ax 的核心代码实现细节3.1 请求主流程从参数合并到网络发起ax 的请求过程可以分成三个大阶段合并配置、执行拦截器链、交给适配器发起。合并配置是整个流程的地基所有后续行为都依赖于这一步产出的完整 config 对象。// core.js 核心片段 async request(config) { const mergedConfig { ...this.defaults, ...config, headers: { ...(this.defaults.headers || {}), ...(config.headers || {}) } }; let promise Promise.resolve(mergedConfig); const reqInterceptors this.interceptors.request.handlers; const resInterceptors this.interceptors.response.handlers; // 把所有请求拦截器放到 dispatchRequest 前面 const chain [this.dispatchRequest, undefined]; reqInterceptors.forEach(interceptor { chain.unshift(interceptor.fulfilled, interceptor.rejected); }); while (chain.length) { promise promise.then(chain.shift(), chain.shift()); } // 响应拦截器按添加顺序依次包裹 resInterceptors.forEach(interceptor { promise promise.then(interceptor.fulfilled, interceptor.rejected); }); return promise; }注意这段拦截器链的实现没有用 async/await 去写循环而是用一个静态 chain 数组配合 Promise.then 来串接。这样做的原因是拦截器本质上是函数序列顺序有严格要求请求拦截器按添加顺序正着执行响应拦截器按“装饰器”的方式依次包在外面。你可以在拦截器里写任意多个方法它们在请求前后各自形成一个队列这种组合方式比简单的 if 嵌套要清晰得多而且天然支持异步操作——比如在 request 拦截器里刷新 token只要返回的 Promise 在刷新完成后 resolve 即可。接下来是 dispatchRequest 的核心动作把合并后的 config 交给适配器然后对响应做初步包装。async dispatchRequest(config) { const url buildURL(config.baseURL, config.url, config.params); const response await httpAdapter({ ...config, url }); return { status: response.status, statusText: response.statusText, data: response.data, headers: response.headers, config }; }为什么 dispatchRequest 不直接返回业务数据而是包一层 response 对象因为响应拦截器里可能有多种场景想拿到完整响应比如 201 状态时要读取 location 头、文件上传完成时要拿进度百分比。如果直接把数据裸露出去这些信息就丢了。包装成一个标准对象后响应拦截器既可以处理业务数据也可以根据 status 做链路分支。3.2 拦截器机制用队列实现请求前后的统一切口拦截器是 ax 里业务接入面最广的部分几乎人人都会用但很多人没想过它内部怎么把请求前的逻辑放到请求前面。上节代码里我用 chain.unshift 把 request 拦截器插入到调用链前方这里是拦截器管理器的完整实现。// interceptors.js class InterceptorManager { constructor() { this.handlers []; } use(fulfilled, rejected) { this.handlers.push({ fulfilled, rejected }); return this.handlers.length - 1; } eject(id) { if (this.handlers[id]) { this.handlers[id] null; } } forEach(fn) { this.handlers.forEach(h { if (h ! null) fn(h); }); } }拦截器整体是一个 Promise 链。核心顺序是请求拦截器按 use 的先后顺序从外到里执行响应拦截器按 use 的先后顺序从里到外执行。也就是说后添加的请求拦截器更加贴近网络请求后添加的响应拦截器则更接近业务侧。很多开发者把请求拦截器当成“配置加工器”、把响应拦截器当成“数据解包器”这是最常见的用法。但如果你想在响应拦截器里做日志上报要注意顺序后加的响应拦截器会先拿到数据便于在数据流出 ax 之前截获。我特别想提醒一个易错点拦截器里必须 return config 或 Promise 链上的值。如果你在 request 拦截器里只修改了 config 却没有 return那下一个环节拿到的是 undefined请求会静默失败且很难排查。我在接业务时踩过一次当时加了打印日志都看不到请求发出排查了快半小时才发现是某个拦截器少了 return。这个坑我在后面问题清单里还会再提到因为它的隐蔽程度真的很高。3.3 超时控制与请求取消两个机制要分清超时和取消这两个能力在 XHR 适配器里是两套写法但它们的核心思路其实相通都要拿到一个外部可以随时叫停的句柄。对 XHR 来说超时用xhr.timeout ontimeout取消用xhr.abort对 fetch 来说两者都靠 AbortController。// adapter/xhr.js export default function xhrAdapter(config) { return new Promise((resolve, reject) { const xhr new XMLHttpRequest(); const method config.method.toUpperCase(); const url config.url; xhr.open(method, url); Object.keys(config.headers).forEach(key { if (config.headers[key] ! undefined) { xhr.setRequestHeader(key, config.headers[key]); } }); if (config.timeout) { xhr.timeout config.timeout; xhr.ontimeout () { reject(createError(timeout, config, ECONNABORTED)); }; } if (config.cancelToken) { config.cancelToken.promise.then(cancel { if (!xhr.aborted) { xhr.aborted true; xhr.abort(); reject(cancel); } }); } xhr.onerror () { reject(createError(network error, config, ERR_NETWORK)); }; xhr.onreadystatechange function () { if (xhr.readyState ! 4) return; const status xhr.status; if (status 0) return; const response { data: parseResponse(xhr.responseText, config.responseType), status, statusText: xhr.statusText, headers: parseHeaders(xhr.getAllResponseHeaders()), config }; if (status 200 status 300) { resolve(response); } else { reject(createError(request failed, config, mapStatusToErrorCode(status), response)); } }; xhr.send(config.data); }); }这里有几个细节值得单独说。第一xhr.ontimeout触发后 Promise 会被 reject但浏览器层面的 XHR 其实已经自己中止了不需要再手动调 abort否则可能触发 onabort 导致二次 reject。第二对于取消令牌的监听我用config.cancelToken.promise.then(...)这个 promise 一执行 cancel对应的 XHR 立刻 abort 并 reject但如果请求已经完成就不能再搅和了所以用xhr.aborted这个标志位挡住。第三状态码 0 的情况一般出现在请求被取消或混合内容拦截没必要当作正常响应解析直接 return 就行。3.4 响应处理与错误分类让业务侧从 if 地狱里解放出来请求发出去了回包到达后ax 要做三件事判断状态码是否在 2xx 范围、把 responseText 解析成合适的数据结构、把错误按照类型打上标签。我定义了一套精简的错误码覆盖了日常项目绝大部分场景。错误码含义典型场景ECONNABORTED请求超时被中止接口 10s 未返回ERR_NETWORK网络层错误断网、DNS 解析失败ERR_CANCELED主动取消组件卸载时取消请求ERR_BAD_REQUEST4xx 请求错误参数校验失败、未授权ERR_BAD_RESPONSE5xx 服务端错误后端服务挂了、网关 502错误分类的价值不在于给人看而在于让业务代码能精确拦截。比如全局错误提示里对 ERR_CANCELED 应该静默因为它通常是路由切换导致的副作用对 ERR_BAD_RESPONSE 可以弹一个“服务暂时不可用”对 ECONNABORTED 则提示检查网络。如果没有统一的错误码业务那边只能去读 error.message 字符串既不稳定也没法做分支处理。4. 把 ax 接入真实项目从封装到落地4.1 在业务代码里怎么封装才能让组件更干净很多项目把 axios 直接用然后每个页面自己写 try/catch 和 loading最终代码里到处是重复的错误提示。用 ax 之后我的习惯是再包一层 request 实例让业务侧只关心数据和语义化异常。// src/api/request.js import { Ax } from ./ax; const service new Ax({ baseURL: import.meta.env.VITE_API_BASE_URL || /api, timeout: 8000, headers: { Content-Type: application/json } }); service.interceptors.request.use(config { const token store.getToken(); if (token) { config.headers.Authorization Bearer ${token}; } return config; }); service.interceptors.response.use( response { const entity response.data; if (entity.code ! 0) { const err new Error(entity.message); err.bizCode entity.code; return Promise.reject(err); } return entity.data; }, error { if (error.code error.code.startsWith(ERR_)) { return Promise.reject(error); } const status error.response?.status; switch (status) { case 401: redirectToLogin(); break; case 403: showMessage(没有权限); break; case 500: showMessage(服务器开小差了); break; default: showMessage(error.message || 请求失败); } return Promise.reject(error); } ); export function get(url, params, config {}) { return service.get(url, { ...config, params }); } export function post(url, data, config {}) { return service.post(url, data, config); } export default service;这样封装之后组件里的请求就变成const data await get(/user/info, { id: userId }); setInfo(data);我不再需要每个请求里写 try/catch 去处理 401也不需要每个页面重复写 loading 状态。loading 可以通过拦截器计数器统一处理也可以交给 useRequest 这种 hook。特别建议把 get/post 再包成具名函数这样 IDE 搜索请求的引用位置会非常快排查问题效率很高也方便后续在函数内部做参数默认值、埋点上报等扩展。4.2 和现有技术栈的搭配React、Vue、小程序都能用ax 是纯 JavaScript 的请求层不绑定任何框架所以接入 React 和 Vue 都很直接。以 Vue 为例我一般会在 main.js 里把封装好的 service 挂到 provide 上这样页面里通过inject($ax)就能拿到实例不需要每个组件顶部重复 import。React 的话我更推荐直接用 hooks 封装比如下面这个简化版 useAxiosfunction useAxios(url, options {}) { const [data, setData] useState(null); const [loading, setLoading] useState(false); const [error, setError] useState(null); const controllerRef useRef(new CancelToken()); useEffect(() { const controller new CancelToken(); const fetchData async () { setLoading(true); try { const result await service.get(url, { ...options, cancelToken: controller.token }); setData(result); } catch (e) { if (service.isCancel(e)) { return; } setError(e); } finally { setLoading(false); } }; fetchData(); return () controller.cancel(); }, [url]); return { data, loading, error }; }这里 hook 的 cleanup 里调controller.cancel()是防止组件卸载之后还收到过期响应。很多前端项目重复渲染导致的竞态基本都是少了这一步。如果你的请求不涉及组件销毁场景那也可以不做取消但在列表页、详情页这种高频率路由切换的页面建议还是加上否则可能出现 A 页面的接口响应把 B 页面的状态覆盖掉的诡异问题。小程序环境如 Taro、uni-app用的是内置 request API没法直接复用 ax 的 XHR 适配器但拦截器部分可以完整保留。你只需要把 dispatchRequest 里的 httpAdapter 替换成小程序封装好的 request 函数即可ax 的核心价值依然存在。这说明适配器拆分的价值不只在于代码整洁它直接决定了这个工具的可移植范围。4.3 TypeScript 类型标注让调用方少踩坑ax 的核心代码是用 JS 写的但对外类型声明我用 TypeScript 补全了否则在 TS 项目里用 ax 会一路 any体验太差。类型定义的重点是 config、response、error 三类对象。export interface AxRequestConfig { url?: string; baseURL?: string; method?: get | post | put | delete | patch; params?: Recordstring, any; data?: any; headers?: Recordstring, string; timeout?: number; responseType?: XMLHttpRequestResponseType; cancelToken?: CancelToken; } export interface AxResponseT any { data: T; status: number; statusText: string; headers: Recordstring, string; config: AxRequestConfig; } export interface AxErrorT any extends Error { code?: string; config: AxRequestConfig; response?: AxResponseT; }写类型声明时有个小技巧getT返回PromiseT这个 T 指的是响应拦截器剥壳之后的业务数据类型而不是 AxResponse。因为我们在拦截器里已经把数据萃取出来了调用方期望拿到的自然是业务数据。如果你把返回类型写成PromiseAxResponseT那每个调用点都得再剥一层非常别扭。类型设计要跟着实际运行时的数据形态走否则“看似完善”的类型声明反而会误导人。5. 从零到上线ax 落地过程中的典型问题与排查笔记5.1 超时了但请求还在跑是怎么回事我在用 ax 的第一个真实项目里就撞上了这个问题设置了 timeout 8000网络很慢时确实在 8 秒后收到了超时报错但浏览器的 Network 面板里请求依然处于 pending 状态后端日志里也看到这个请求最后被处理了。为什么超时 reject 了请求却还在跑原因在于 XHR 的超时只是“前端不等待响应了”并不是真的把服务端请求撤回来。终止请求取决于浏览器行为在部分浏览器中xhr.timeout到达后会自动 abort但如果后端已经长时间不返回TCP 连接并不会被立刻回收表现就是请求还挂在网络面板里。处理思路有两个一是超时后如果服务端其实已经处理完前端只是不想继续等待那超时错误是合理的二是如果需要更严格的“请求终止”要靠取消令牌触发xhr.abort()这样浏览器会立即断开连接。所以 ax 的超时和取消是两个独立机制超时管“我不等了”取消管“我强制掐断”业务上要区分开。5.2 拦截器里改了 config但请求发出去还是没有变更这个问题的根源几乎都是在 request 拦截器里修改了 config 中某个字段但 dispatchRequest 用的却是另一个对象。比如你以为直接改了 config.url实际上 URL 拼接逻辑用的是buildURL(config.baseURL, config.url, config.params)的结果而不是 config.url 本身。如果你在拦截器里改的是 params要记得用新值重新走 buildURL否则拼出来的地址还是旧的。另外还有一种常见情况拦截器里手动写了config.headers[X-Custom] abc但 headers 在合并配置时可能被后续的默认头覆盖。因为合并阶段我采用的是浅拷贝合并如果某个 key 在默认配置里已经存在拦截器里的赋值会被覆盖得无声无息。要避免这种情况最好的办法是拦截器全部执行完后再做 header 合并或者在拦截器里显式写成config.headers { ...config.headers, X-Custom: abc }把合并路径交给新对象。排查这类问题时我一般会在 dispatchRequest 的第一行打印 config对比哪一层丢了字段。5.3 取消请求之后Promise 竟然走进 then 而不是 catch这个坑来自取消令牌和响应状态判断的先后顺序。我在最初的实现里cancelToken 的 promise 一旦 resolve就直接xhr.abort()但 onreadystatechange 里如果对 readyState ! 4 的包直接 return理论上不会产生新的 resolve。不过如果你在 abort 之前已经把 readyState 变为 4比如服务端响应非常快数据已经回来了abort 之后再检查 status 时就会被代码命中走 resolve 分支。我的修复方案是引入一个 aborted 标志位一旦取消就把xhr.aborted置为 true然后在 onreadystatechange 里判断如果xhr.aborted就直接 reject 取消错误不再走正常状态判断。这个标志位既防止了状态竞争也避免了重复 reject 导致 Promise 状态被覆盖。使用取消令牌时的原则是取消之后所有后续回调都不应再触发 resolve宁可多打一个日志也不要让数据流被切断后还继续流动。5.4 并发请求多时要不要加请求合并或缓存做管理后台的时候同一个字典接口在页面初始化时会被五六个组件同时调用后端接口设计又不支持批量查询于是每个组件都发了一次请求。这种场景我用 ax 做了两个层面的优化请求合并和结果缓存。请求合并思路是在短时间内如果多个请求的 url 完全相同就只发一个请求让所有调用方共享同一个 Promise。实现上可以在 dispatchRequest 里维护一个 Mapconst pendingMap new Map(); async function dispatchWithMerge(config) { const key ${config.method}-${config.url}-${JSON.stringify(config.params || {})}; if (pendingMap.has(key)) { return pendingMap.get(key); } const p httpAdapter(config).finally(() { pendingMap.delete(key); }); pendingMap.set(key, p); return p; }结果缓存则适用于字典类稳定数据首次请求成功后把数据存到模块级 Map 里后续直接返回缓存值同时提供一个 forceRefresh 参数绕过缓存。这两个优化看起来不复杂但对接口压力非常大的中后台页面来说收益很实在也体现了自研请求库的灵活性——如果你用别人的库加这种自定义能力会比较绕。当然请求合并也有坑比如不同页面带不同的 token合并后可能共享了不该共享的凭证所以合并键里务必把鉴权头也拼进去。6. ax 写成之后我沉淀下的几点体会ax 从设计到落地用了大概三天其中半天写核心一天半补适配器和拦截器剩下半天在项目里接入并解决上面几个问题。这段经历给我最大的感受是请求库根本不是“写个 get 方法”那么简单真正难的是把超时、取消、拦截器顺序、错误分类、类型推导这些边界行为想清楚。任何一个环节处理不好上线后都会以各种诡异的形式冒出来比如页面偶尔白屏、接口重复请求、401 提示弹不够。如果你也想动手写一个自己的 ax我的建议是不要一步到位先实现一个最基础的单文件版本满足你当前项目的 80% 需求再逐步把拦截器、取消、适配器拆分出来。每加一个能力都要反问自己这个能力是给我的业务用的还是为了显得很完整功能膨胀是自研库最容易犯的错保持克制的收益比多写两个炫技方法大得多。另外一个很实用的技巧把 ax 的源码直接放在自己项目里而不是打成 npm 包再引回来。因为请求层会跟着业务演化比如增加公司统一的埋点 header、根据环境切换 baseURL这些逻辑放在源码仓库里可以直接改、直接看 diff比依赖一个“黑盒 npm 包”要踏实得多。等哪天你真的做了一套通用配置再抽成独立包也不迟。最后分享一个小经验写请求库或者任何底层工具时务必给自己留一个 debug 模式。ax 里我加了一个开启后打印完整 config、拦截器执行顺序、适配器输出日志的方法排查线上问题时就靠它快速定位是配置问题还是网络问题。这个功能本身不过几行代码但它能在你最焦头烂额的时候帮你省下一整晚的排查时间。
