Axios二次封装实战:鉴权、重复拦截、Loading、缓存与统一错误处理
去年年中我重构一个后台管理系统时,顺手做了一套 Axios 二次封装。当时项目里十几个页面裸调 axios,每个页面自己拼 token、自己 try/catch,遇到 401 就跳登录页,接口报错提示风格五花八门。那段时间线上天天有人反馈“点了按钮没反应”,排查下来全是重复提交、缓存失效、loading 状态捣乱。后来我把鉴权、重复拦截、Loading、缓存、统一错误、请求重试这六件事全部收拢到同一层,代码反而少了三分之一,排查问题也快了很多。这篇就把完整的封装方案拆开写清楚,代码带逐行注释,你在自己项目里可以直接抄。
这套方案适合什么场景?中等规模以上的中后台项目、管理后台、H5 应用,凡是存在多页面重复请求、token 过期需要统一处理的,都适用。如果你的项目只有三五个接口、没有登录态,那后面的鉴权和重试部分可以跳过,但重复拦截和缓存的设计思路仍然值得参考。
1. 从裸奔到统一出口:为什么要做这套封装
1.1 散装 axios 带来的四个问题
散装请求通常长这样:每个页面自己 axios.get(...),请求头里自己塞 token,loading 自己搞个变量控制,报错自己 alert。表面看没什么不妥,但项目一大人就麻了。我总结下来至少四个痛点。
第一个是鉴权逻辑散落。token 过期后每个页面跳登录页的方式都不一样,有的 window.location.href,有的 router.push,还有的直接白屏。第二个是重复请求没人管。用户双击搜索按钮、快速切换 Tab、Table 组件内部多次触发查询,同一个接口能发出去三四次,数据库压力倒是小事,界面数据经常被后返回的旧数据覆盖,体验很糟糕。第三个是 loading 状态很难维护。并发三个请求,每个请求都在 finally 里把 loading 置 false,结果前两个先返回,第三个还在跑,loading 就提前消失了。第四个是错误处理不统一。后端返回 { code: 50010, message: '余额不足' },有的页面只 console.log,有的页面直接弹窗,有的直接把后端 message 扔给用户看,后端文案写得再烂也没人拦着。
这些问题的根子不是 axios 不好用,而是缺少一个统一的出口。所谓出口,就是所有请求必须经过同一个方法发出去,所有拦截逻辑都挂在这条链路里。这样改动鉴权规则、调整错误提示、加缓存策略,都只动一处。
1.2 封装边界:拦截器、实例、方法层各自做什么
很多同学一上来就把所有逻辑塞进拦截器,结果拦截器写得跟裹脚布一样。我建议分成三层思考。
第一层是 axios 实例层,负责最基础的配置:baseURL、超时时间、请求头默认值。这一层不需要太多业务逻辑。第二层是拦截器层,负责所有请求“经过这里一次”的切面逻辑:注入 token、生成请求指纹、登记 pending、打开 loading;响应回来时移除 pending、关闭 loading、处理 HTTP 错误和业务错误码。第三层是方法层,也就是我们自己暴露出去的 request 函数。这一层做两件拦截器不太好做的事:一是缓存命中时直接返回数据,根本不需要发请求;二是重试逻辑的递归调用,因为重试需要重新走一遍完整链路。
我见过有的封装把缓存判断也放进请求拦截器,通过自定义 config 字段去分支判断,然后抛一个 Promise.reject 来“短路”。这样做确实能实现,但会干扰 pending 和 loading 的计数,还要额外标记“本次不是错误”。我自己试下来,在方法层判断缓存最干净:命中缓存直接 return,不污染拦截器的状态机。
1.3 目录设计与基础配置
我习惯把封装独立成一个目录,不要散落文件。下面这个结构足够清晰:
拆文件不是为了炫技,而是让每个模块的职责一眼能看出来。修改缓存策略时不用碰鉴权代码,排查 loading 问题时只需要看 loading.js。团队协作时也不容易产生冲突。
config.js 里我会放这些基础常量:
超时时间我给 10 秒,不是拍脑袋。后台管理系统的接口大多在 2 秒内返回,超过 10 秒基本可以判定为异常。设太短容易误杀慢查询,设太长用户等得焦虑。移动端或者弱网环境另说,通常要调到 15 到 20 秒。
2. 鉴权模块:token 注入与 401 兜底
2.1 token 存取与请求头注入
鉴权封装的第一个基础是 token 的存取。生产环境里 token 放 localStorage 还是 sessionStorage 取决于产品需求:如果是管理后台,关掉浏览器后希望重新登录,用 sessionStorage;如果希望下次打开还保持登录,用 localStorage。多数后台用的 localStorage。
auth.js 里有几个函数,逻辑非常简单但值得统一收口:
很多人会问:能不能把 token 直接放在内存变量里,比 localStorage 安全?内存变量确实能避免 XSS 通过 localStorage 偷取 token,但刷新页面就丢了,需要额外接口恢复登录态。大多数中后台项目并不需要这么高的安全等级,localStorage 加 HttpOnly Cookie 的方案看团队基础设施。我这里按通用方案走。
注入头的动作放在请求拦截器里。注意团队里要约定好后端要的字段名,是 Authorization: Bearer xxx 还是自定义头 X-Token: xxx。我项目里用的是 Authorization: Bearer,这也是最通用的格式。
2.2 401 统一拦截,但要防止重复跳转
响应拦截器里需要专门处理 HTTP 401。401 表示登录态失效,所有页面都会收到这个状态码,如果不做处理,会出现一个很经典的故障:页面里同时挂着三个接口,三个接口都返回 401,代码里每个错误处理分支都跳一次登录页,用户就被反复重定向,浏览器后退键直接失灵。
解决办法是加一个「跳转锁」。用模块级布尔变量记录是否已经在跳转,只有第一次 401 才执行跳转逻辑,后续 401 直接忽略。代码是这样:
什么时候重置这个布尔变量?两个时机:一是手动点击登录页跳转成功;二是退出登录时。否则用户登录成功后 isRedirecting 还是 true,下次 401 就不会再跳了。加一个 resetAuthState() 函数,在登录接口成功或退出登录时调用。
还有一个细节:如果项目用了 Vue Router 或 React Router,用 router.replace 跳转优先于 window.location.href,因为前者不刷新页面,能保留应用内部状态。但单页应用里的 router.replace 遇到 hash 模式有个问题——登录页地址不会带完整的原始路径,我习惯在 401 时保留 window.location.href 作为 redirect 参数,登录成功后整页刷新回去,对后端无感知。
2.3 HTTP 状态码与业务返回码的分层处理
这是封装里最容易被搞混的部分。HTTP 状态码是传输层状态,业务返回码是应用层状态。很多后端即使业务失败也会返回 HTTP 200,只在 body 里写 code: 50010。反过来,HTTP 401 也可能对应后端返回体的不同 code。
正确做法是分层判断。在响应成功分支里,判断 response.status 是否为 2xx,再判断 response.data.code 是否为 0(按你们后端约定)。两者都通过才算成功。
业务错误码的提示不能扔给 HTTP 错误映射表处理,因为后端业务码可能很多。我在 config.js 里维护一份 BUSINESS_ERROR_MAP,常用的放进去,未知 code 使用后端返回的 message 兜底。这样做的好处是提示语可以和后端解耦,后端改文案不用发版,前端也能对特定 code 做特殊逻辑,比如某个业务码需要打开新的引导弹窗。
3. 重复请求拦截与全局 Loading 管理
3.1 请求指纹:如何判断“同一个请求”
要拦截重复请求,第一步是给请求生成指纹。指纹的规则必须是:相同请求生成相同 key,不同请求生成不同 key。我用的字段是 method + url + params + data 的拼接。params 和 data 在序列化之前要先做一次 JSON.stringify,否则对象引用不同会导致 key 不一致。
这里有一个坑:JSON.stringify 对对象属性顺序很敏感,{ a: 1, b: 2 } 和 { b: 2, a: 1 } 会生成不同的 key。如果页面代码里两次请求的传参顺序不一致,就会被误判为不同请求,拦截失效。解决方法是写一个稳定序列化函数,对对象 key 排序后再序列化。项目接口相对规范的话,不排序也能用,但一旦出现上面这种情况排查起来很费劲。我用的是这种写法:
3.2 AbortController 取消上一个请求(防抖模式)
拿到指纹后,需要一个容器来登记“正在进行的请求”。我用的 Map<key, AbortController>,key 是请求指纹,value 是对应的取消控制器。
这里实现的是「取消上一个、保留最新」的抢占式策略。用户连续点击两次搜索,第一次请求发出后未返回,第二次点击到达时第一次请求被 abort,只保留第二次。这种策略对大多数 C 端场景更友好,因为用户可以快速重新触发,界面显示的是最新结果。
另一种策略是「丢弃本次、保留上一个」。第一次请求在途时,第二次点击直接短路返回上一次的 Promise,甚至从缓存里取值。这适合成本高的请求,比如重复提交表单。绝大多数场景我推荐抢占式,因为它实现简单,语义上也更符合“用户最后一次操作最重要”的原则。
取消请求会导致 axios 抛一个 CanceledError,这个错误会被响应错误分支捕获。需要判断 axios.isCancel(error),是取消错误就直接静默处理,不要弹错误提示,也不要走重试逻辑。后面踩坑部分我会专门说这个。
3.3 Loading 计数器:并发请求不能用一个 boolean
全局 Loading 用 boolean 控制是最大的坑。设想三个请求并发:第一个完成时想置 false,第二个还在飞,界面 Loading 就没了。正确方案是计数器。
计数器必须保证「每加一次就必减一次」。请求拦截器里 openLoading() 后,响应拦截器成功分支和错误分支都要 closeLoading()。如果某个分支因为 removePending 提前 return 忘了关闭,计数器就会泄漏,表现为 Loading 永远转圈。后面踩坑部分我会给出一个更容易排查的变体:给每次 Loading 加上短延迟防闪烁,比如请求在 300ms 内完成就不显示 Loading,避免高频刷新接口让 Loading 一直闪烁。
4. 缓存模块:TTL 缓存与手动失效
4.1 缓存对象设计
缓存模块我直接用 Map 实现,不引第三方库。每份缓存要记录三个信息:响应数据、存入时间戳、有效期(TTL)。建议所有缓存放在同一个 Map 里,按指纹做 key。
读取缓存时发现过期,直接删除并返回 null,保证不返回脏数据。为什么用 Map 而不是 Object?因为 Map 天然支持任意类型 key,删除和取值都是 O(1),而且不会受到原型链污染影响。另一个理由是 Map 有迭代顺序,将来要做 LRU 淘汰策略、按过期时间批量清理,Map 更方便。
4.2 缓存命中与写入时机
缓存的读和写时机是这套方案里最需要注意的。读时机放在方法层的开头,也就是真正调用 axios 实例之前。一旦命中缓存,整个链路都不需要走了,loading、pending 全部跳过。
写时机放在请求成功后。但注意不能凡是 GET 都缓存,有的接口虽然方法是 GET,但数据实时性要求很高,比如订单状态、库存数。我通过自定义 config 字段控制,只有显式声明 cache: true 的请求才参与缓存。
这里有一个设计取舍:写缓存的数据是 response.data 还是整个 response?我们项目的后端返回体是 { code, message, data },响应拦截器成功分支已经把 response.data 抛出来了,所以 request 函数拿到的 response 就是业务数据。直接把这份数据缓存即可。但要注意,缓存中保存的是对象引用。如果页面拿到缓存后直接修改了对象属性,缓存也会被污染。稳妥起见,写入缓存前做一次浅克隆 { ...response },虽然增加一点内存开销,但能避免绝大多数脏数据问题。
4.3 缓存穿透、缓存污染与手动刷新
缓存穿透最典型的表现是:同一时刻有 10 个页面在请求同一个列表接口,缓存还没有建立,10 个请求全部打到后端。这个问题在服务端缓存里叫 stampede,前端同样存在。解决方案有两个:要么在 pending 阶段就拦截,已经有一个同指纹请求在途时,后面的请求直接共享这个 Promise,也就是 singleflight;要么干脆接受这种现象,毕竟前端缓存场景下并发量通常不大。我在实际项目中是结合 pending 机制处理的,因为 pendingMap 本身就记录了在途请求,等第一个请求回来时把结果写入缓存,后面的请求自然就能命中。这个做法不用额外代码,只要保证缓存写入发生在 pending 移除之前就行。
缓存污染则是另一个问题。比如用户修改了个人资料,列表页还缓存着旧数据,刷新列表时拿到的是旧值。处理办法是提供手动失效接口。我在 cache.js 里导出一个 removeCache(key) 和 clearCache(),业务代码里修改完数据主动调一下。更优雅的方案是事件广播:用户数据变更后,发一个 CACHE_INVALIDATE 事件,全局缓存模块监听后根据规则清理。小项目用不上事件,直接 clearCache() 最省事。
5. 统一错误处理与请求重试
5.1 错误分类:网络错误、超时、业务错误
统一错误处理的前提是把错误分类清楚。我分成四类:网络错误(断网、DNS 解析失败)、超时错误、业务错误(HTTP 200 但业务 code 非 0)、HTTP 状态码错误。每类的处理策略不同。
网络错误和超时错误要提示“网络异常,请检查网络”,同时可以考虑自动重试。HTTP 状态码错误按照 HTTP_ERROR_MAP 提示。业务错误使用业务码映射或后端 message。四类错误的共同出口是交给 notifyErrorMessage 函数。项目里如果用的 Element Plus,里面直接 ElMessage.error(msg);如果用 Antd,就是 message.error(msg)。我把这个函数放在 config 里导出,方便统一替换。
UI 组件库千差万别,封装层不应该直接 import 某个库的组件。定义一套 messageHandler 注入机制,让项目入口把 ElMessage 或 antd 的 message 塞进来,封装层保持纯净。这是我后来重新整理时才明白的改进。
5.2 指数退避重试,但要守住幂等底线
请求重试是双刃剑。用得不好,后端慢查询没恢复,前端反而加大压力。重试策略必须满足两个前提:请求是幂等的、错误类型是可重试的。
幂等性判断很简单:只对 GET、HEAD、PUT、DELETE 做自动重试。POST 默认不重试,因为 POST 常用于创建订单、提交表单,重试可能造成重复提交。如果业务确有“POST 对账接口需要重试”的需求,在个别调用处显式传 retry: 2,前端开发者自己要承担重复提交的风险。
错误类型判断:4xx 业务错误不重试,5xx 和网络错误才重试。401 不重试。400 不重试,那是参数写错了,重试多少次都一样错。
指数退避公式是 delay = baseDelay * 2^retryCount。第一次重试等待 1 秒,第二次 2 秒,第三次 4 秒。这个递进速度可以在“快速恢复”和“避免压垮服务端”之间取得平衡。
sleep 函数很简单,return new Promise(resolve => setTimeout(resolve, ms))。重试时要注意:config 是已经注入过 token 和 pending 的旧配置,重新走 request 方法会再次走拦截器,token 会重新注入,pending 也会重新登记。没问题。但旧配置里可能带着上次的 signal,如果上次的 AbortController 还没取消,会带着旧 signal 发出请求。我通常在重试前把 config.signal 清掉,让新的拦截器重新绑定。
5.3 超时与取消的配合
axios 的 timeout 配置同时作用于整个请求生命周期。但超时和手动取消之间存在竞争:如果超时时间到了,axios 抛出 ECONNABORTED,这时配置里的 signal 已经没意义了。另一个坑是 timeout 默认值是 0,表示不超时,这会让用户一直等下去。我在实例里统一设了 10 秒默认,允许单个请求通过 config.timeout 覆盖。
超时的错误处理重试时还有一个细节:超时错误对象上,axios 会附带 error.code = 'ECONNABORTED'。重试函数里判断 'ECONNABORTED' 才能识别超时并触发重试。有些同学用 err.message.includes('timeout') 判断,这个很脆弱,因为不同环境下的超时文案不一样。统一用 error.code 判断最稳。
6. 完整代码示例与使用方式
6.1 封装文件完整代码(带逐行注释)
前面五章把每个模块拆开讲了,现在给一份整合后的完整代码。文件是 src/utils/request/index.js,所有模块合并在一个文件里方便复制。生产环境建议还是拆分到多文件。
这个文件可以直接放到项目里用,替换原来散落的 axios 调用。
6.2 页面里的调用方式
用起来非常方便,普通请求不需要任何额外参数:
需要缓存的 GET 接口,传 cache: true:
修改了字典后,手动清干净:
需要全局 Loading 和重复拦截是默认行为,不需要配置。需要关闭全局 Loading 的请求(比如上传进度条场景),传 loading: false,不过上面的代码还没有实现这个开关。实际项目里我会在拦截器里加个判断:
请求超时或网络错误需要重试的,传 retry:
这样单个接口用了 2 次重试机会,每次基础间隔 1 秒。配合指数退避,实际等待时间分别是 1 秒和 2 秒。
7. 实测踩坑记录与常见问题速查
7.1 CanceledError 被当成错误提示
我第一次写完重复拦截时,发现控制台疯狂报错,页面上弹了无数“请求失败”。原因很简单:被 abort() 的请求会进入 axios 的错误分支,axios.isCancel(error) 判断写在了很多逻辑之后,导致取消错误先触发了 notifyErrorMessage。
修正方式是把 isCancelError 判断放最前面,取消错误不弹提示不重试,直接静默 reject。但注意,removePending 和 closeLoading 要照常执行,否则状态会泄漏。
这个坑还衍生出一个设计问题:第一个请求被取消时,调用方可能正在 await request.get(...) 的 try/catch 里,取消导致的 reject 会被业务代码捕获。如果业务代码把任何 reject 都当成错误处理,就会在页面里报一个无关错误。处理办法有两个,要么在业务侧判断 axios.isCancel,要么让被取消请求静默失败不触发调用方错误逻辑。我实际采用后者更多,因为改调用方成本太高。具体做法是在方法层捕获取消错误,直接返回一个特殊值,业务代码基本无感。
7.2 Loading 计数器泄漏的三个典型场景
Loader 一直转圈是封装上线后最容易出现的线上事故。我排查过三个典型场景。
第一个是请求拦截器抛错。如果拦截器在 openLoading() 之后、在 config 生效之前抛了异常,请求根本没发出去,响应拦截器也不会执行,计数器直接泄漏。解决方案是拦截器里所有可能抛错的分支都要 catch,并在 catch 里手动关闭 loading。
第二个是响应成功分支里 business code 非 0 的情况。有些同学在成功分支中发现业务码不对,直接 return Promise.reject,但忘记 removePending 和 closeLoading。这个能通过代码检查补掉。
第三个是带超时的取消。请求发出去后超时,错误对象上的 config.signal 是同一个 controller 的 signal。如果在超时错误分支里误判为取消而停止执行后续逻辑,要小心计数器一致性。
最实用的调试方法是在 closeLoading 里打日志,输出 pendingCount 和当前 URL。线上出现 Loading 卡死时,按时间线看日志,一眼就能找到哪个请求把计数器卡住了。
7.3 请求重试与并发重复请求叠加的坑
重试和 pending 拦截同时开启时,有个隐藏 bug。请求 A 第一次失败会触发重试,重试时 config 是旧对象,__retryCount 已经被 +1。但 pending 拦截器会根据指纹重新登记。如果这个请求还没完成,用户又触发了一次相同请求,第二次请求会 abort 掉正在重试的第一次请求,然后第一次请求的 retryRequest 捕获到 CanceledError,继续进入 retryRequest 判断。因为 isRetryableError 不认为取消错误可重试,会直接 reject。用户看到的表象是:重试中的请求被自己人给杀了。
解法是重试时对取消错误不做处理,直接放行,同时在 retryRequest 的入口加一个取消错误判断:
这样避免了重试栈被取消请求反复触发,也让 pending 拦截更加稳定。
7.4 常见问题速查表
| 现象 | 原因 | 解决方案 |
|---|---|---|
| 页面反复跳登录页 | 多个 401 并发触发跳转逻辑 | 用 isRedirecting 布尔变量做跳转锁 |
| Loading 永远转圈 | 某些错误分支没关闭计数器 | 统一在响应成功的两个分支和错误分支都执行 closeLoading |
| 列表数据修改后还是旧值 | GET 缓存未失效 | 手动调用 removeCache 或 clearCache |
| 双击按钮提交了两次订单 | POST 请求没有被重复拦截 | 对 POST 请求也做 pending 登记,或按钮侧防重复 |
| 同一个请求不同参数被误判为新请求 | JSON.stringify 对 key 顺序敏感 | 使用 stableStringify 对 key 排序后再生成指纹 |
| 取消请求后页面报错 | 取消错误没有静默处理 | axios.isCancel 判断放在最前,取消错误不提示不重试 |
| 重试时旧 signal 生效 | 旧 config 上绑定了 AbortController | 重试前删除 config.signal |
| 个别 GET 接口数据频繁变化 | 所有 GET 都缓存了 | 用 cache: true 显式开启缓存,不是默认开启 |
| 断网后多个请求立刻重试,压力过大 | 重试无间隔或间隔不合理 | 用指数退避 delay * 2^retryCount |
| 部分接口不需要全局 Loading | 所有请求都走了 Loading 流程 | 增加 config.loading === false 开关 |
7.5 一个提升体验的小技巧:请求去重时保留第一个请求的结果
重复拦截的抢占式策略有一个反直觉的时刻:第一个请求还没返回,用户误触发了第二次请求,第一次请求被取消,但是第二次请求可能因为参数相同,最终返回的数据其实是同一份。如果接口本身很慢,用户会感到“点了两下,转了两次圈”。这时候比较优雅的做法是保留第一次 Promise,让第二次请求直接复用同一个 Promise。这个模式叫 singleflight,虽然项目里不常用,但在缓存和重复拦截叠加时值得考虑。
实现上就是在 pendingMap 里不仅存 controller,还有一个 promise。第二次请求进入时发现已有在途 promise,直接 return 这个 promise。等结果回来时统一 resolve 给所有调用方。这个方案要注意 Promise 的错误传播:任何一个调用方 throw 都会影响其他调用方。所以还要用 Promise.prototype.finally 或 catch 包一层,保证只有第一个调用方负责清理工作。代码会稍微复杂一点,但确实是少见的优质优化点。
我在实际项目里遇到搜索框连续输入的场景,用了这个方案后,抖动感明显下降,服务器压力也小了一些。如果你的项目存在“同一参数短时间内被多处代码重复请求”的情况,强烈建议试一下。
这套封装整体下来,代码量不算大,但每行背后都对应真实线上踩过的坑。做完之后最大的收益是,新同学接手项目时只需要看 request/index.js 和 config.js,所有请求规则一目了然。相比之前散落各处的处理逻辑,这种集中式方案维护成本低太多了。如果你刚开始做 Axios 封装,建议先按六个模块逐个接入,别指望一步到位。先把鉴权和统一错误做了,再逐步加重复拦截和缓存,每加入一个模块都回归一遍全站请求,你会对这套东西的理解比抄一整份代码深得多。