axios二次封装实战:鉴权、拦截、缓存与重试六合一方案
做前端项目,只要项目里用了 axios,基本都会遇到同一个问题:要不要二次封装?我的答案很直接,只要你的项目超过一个页面、接口数量超过十个,就必须封装,而且要趁早。标题里这六件事——鉴权、重复拦截、Loading、缓存、统一错误、请求重试——不是锦上添花,而是把那些“每个请求都要处理一遍”的横切逻辑,统一收口到 axios 的拦截器里,让业务代码只关心“我要什么数据”,其他破事全交给封装层。这篇就把整个封装思路、每个功能的实现原理和完整代码逐行讲透,适合刚接触二次封装的新手,也适合想把自己封装抽得更干净的老手。我会把踩过的坑、取舍逻辑都写出来,争取让你读完能直接复制到自己项目里改改用。
1. 封装前先想明白:你要的到底是哪六样能力
1.1 二封的本质是统一入口,不是代码洁癖
很多人把 axios 二次封装理解成“代码写得好不好看”的问题,这其实是个误解。不封装的典型场景是这样的:页面 A 里 axios.get 一段,.then 里手动判断 status 是不是 200,再写一段 401 跳登录的逻辑;页面 B 把同样一段复制过去;页面 C 再复制一次。等后端某天改了统一返回结构,或者要全局加一个签名参数,你就得全项目搜索 .then,逐改、逐测,少改一处线上就多一个 bug。
封装的核心逻辑只有一个:把“鉴权、错误提示、loading、缓存、重试、重复请求”这些横切关注点,通过 axios 的拦截器机制集中实现。业务代码里只需要调用一个 request 方法,传 url 和参数,拿回数据就行。这相当于把所有请求的“安检通道”统一到一个入口,每个请求都要走同一套流程:带 token、防重复、显示 loading、缓存命中直接返回、失败自动重试、错误统一提示。
1.2 六项能力怎么取舍
我在不同团队见过很多封装方案,有的恨不得把所有能力都塞进去,有的又只做了个 baseURL 就自称封装。根据实战经验,下面这六项是性价比最高、几乎每个中后台项目都用得到的核心能力。
| 能力 | 解决的真实问题 | 不做的代价 |
|---|---|---|
| 鉴权(token + 401 处理) | 每次请求都要带 token,过期后要统一处理 | 每个页面手动塞 token,token 过期后乱跳登录、白屏 |
| 重复请求拦截 | 用户快速点击查询/提交,连续发同一个请求 | 重复下单、重复查询,后端压力大,前端数据被覆盖 |
| Loading 全局控制 | 请求期间需要全屏/局部 loading | 每个组件各写各的 loading,并发时闪屏或永远关不掉 |
| GET 缓存 | 短时间内重复查询相同数据 | 反复请求同一个接口,浪费流量、拖慢页面 |
| 统一错误处理 | 后端返回各种错误码和网络异常 | 每个页面 try/catch 一堆,提示风格不统一 |
| 请求重试 | 网络抖一下、服务端 5xx | 用户手动刷新,体验差,故障恢复慢 |
这六项有一个共同特点:它们都是“规则明确、全局一致”的逻辑。只要逻辑是全局一致的,就不应该散落在各个页面里,而应该沉淀到封装层。我之前也见过封装里硬塞“权限判断”“埋点上报”“接口监控”的,不是说不行,而是这些逻辑往往带有业务属性,放在封装层会越搅越乱。建议就守住 HTTP 层这六样,业务相关的能力放在上层,别混在一起。
2. 鉴权模块:请求拦截器为什么是放 token 的第一现场
2.1 token 的存取:localStorage、内存变量还是 cookie
鉴权是封装里最基础的一环。token 的存储位置,我建议“双写”:localStorage 持久化一份,保证刷新页面后能恢复;内存变量再存一份,避免每次请求都去读 localStorage,毕竟 JSON.parse localStorage 这种操作在请求频繁时也是开销。
这段代码看着普通,但“双写”这个细节很重要。如果不设内存变量,每次请求都要去 localStorage getItem 一次,虽然现代浏览器不慢,但在高频轮询接口的场景下,积少成多也是性能损耗。而如果只存内存变量,刷新页面就丢了,还得后端允许重新登录才能拿回。
2.2 请求拦截器:在请求发出前把 token 放进 header
axios 的请求拦截器是执行 request(config) 之后、真正发出网络请求之前触发的,这就是加鉴权头的最佳位置。每个请求都会先经过这里,token 只要判断一次,业务代码里完全不用关心 header 的事。
很多人在封装的时候会忘记 FormData 这个细节,直接导致文件上传接口报错。axios 默认情况下,如果你传的是普通对象,会序列化成 JSON 字符串并设置 Content-Type 为 application/json;如果你传的是 FormData,axios 会自动识别并设置为 multipart/form-data 并生成 boundary。一旦在请求拦截器里无脑 config.headers['Content-Type'] = 'application/json',文件上传直接炸。所以上面我用 instanceof FormData 判断一把,如果拦截器检测到是 FormData,就把 Content-Type 删掉,让浏览器自己处理。
2.3 响应拦截器遇到 401:刷新 token 的并发队列
token 是会过期的。最简单的处理是:一旦响应拦截器收到 401 状态码,就跳转登录页。但这样处理在并发请求场景下会出问题:一个页面同时发 3 个请求,3 个请求的 token 都过期了,会同时触发 3 次“跳登录”,还会各自调用刷新 token 接口,造成重复刷新。
正确的做法是维护一个“刷新队列”:第一个 401 触发刷新 token,后续 401 不重复刷新,而是排队等待刷新完成,然后用新 token 重放这些请求。
这个队列方案是我在一个天折的项目里踩坑踩出来的。起初直接每个 401 都调 refreshToken,结果刷新接口短时间被调了七八次,后端直接限流。后来改成队列加锁,刷新接口只需要请求一次,所有并发请求都能安全重放。注意重放时用的是 service(config) 而不是直接 axios,这样会再次经过拦截器,配置、鉴权、防重复都会被重新执行一遍,保证重放请求行为一致。
3. 重复请求拦截:别再让用户手滑点出两个订单
3.1 什么请求才算“重复”
重复请求的定义要精确,不然会误杀正常请求。一个请求如果 method、url、params、data 都一样,且都在进行中(尚未返回),那它就是重复请求。常见场景是用户快速点击查询按钮、表格切页时上一次还没返回又一次触发、表单在 blur 和 click 双事件里都触发了校验接口。
判断重复需要给请求生成一个“指纹”,也就是把请求的特征序列化成一个字符串。这里有个大坑:直接用 JSON.stringify(config.params) 做指纹,一旦对象里键的顺序变了,序列化结果就不同,同一个请求却被判成两个不同请求。所以序列化时要用 qs 库,或者自己递归排序后再序列化。
qs.stringify 的 sort 参数可以稳定序列化对象键的顺序,这样同样的请求不管传参时的对象键顺序如何,生成的指纹都是一样的。这个方法用 qs 而不是 URLSearchParams,因为要支持嵌套对象。
3.2 用 AbortController 取消旧请求,不用 cancelToken
axios 老版本支持 CancelToken API,后来官方推荐改用浏览器标准的 AbortController。原理很简单:创建一个 AbortController 实例,把它的 signal 传给 axios 的 config,外部调用 controller.abort() 就能取消这个请求。
注意取消旧请求并不是唯一的策略,还有一种做法是忽略新请求,让旧请求返回后生效。两种策略使用场景不同:取消旧请求适用于“以最后一次点击为准”,比如搜索框里用户快速输入多个关键词,应该只响应最新的;忽略新请求适用于“以第一次请求为准”,比如按钮防连点。我这份封装里默认采用“取消旧请求”,即新请求会取消旧请求,保证最终使用的是最新一次请求的结果。
3.3 拦截器里自动挂载与清理
有了 addPending 和 removePending,剩下的就是在请求拦截器里加指纹,在响应拦截器里移除指纹。还有一点很关键:取消请求后 axios 会抛出一个 CanceledError,这个错误不能走到统一错误提示的逻辑里,否则每次取消一个请求都会弹一个“请求被取消”的错误提示,用户会被烦死。
axios.isCancel 这个 API 很多人没注意到,它专门用来判断请求是否被取消。如果你不做这个判断,取消请求会走统一错误分支,把取消当成真错误处理,白白弹错。我在一个项目里就是因为少写了这个判断,快速切分页时,页面不停弹“请求出错”,排查了很久才发现是取消请求的误报。
4. Loading 全局控制:计数器是防闪屏和防卡死的钥匙
4.1 为什么单独开一个 loading 模块
每个请求都希望有个 loading 反馈,但如果把 loading 散落在业务组件里,每个组件都要维护自己的 loading 状态,非常啰嗦。把 loading 收进封装层后,业务代码里连 loading 变量都不用声明,甚至还能自动处理并发场景。
但凡是全局 loading,必然要处理两个问题:并发和闪屏。
并发场景:三个请求同时发,第一个先返回,如果此时就关掉 loading,后面两个还在飞,用户会看到 loading 闪一下就没,体验很怪。解法是用计数器,只有计数归零才真正关闭 loading。
闪屏场景:很多接口 100ms 就返回了,全屏 loading 闪一下反而比不显示更干扰用户。解法是延迟显示,比如设置 300ms 的定时器,请求在 300ms 内返回就不显示 loading;超过 300ms 才真正弹出来。
4.2 Loading 模块实现
注意一个关键 bug:如果 hideLoading 里的 loadingCount 没有做 <= 0 的保护,异常情况下可能出现负数,导致 loading 永远关不掉或者计数错乱。我的封装里加了一层兜底判断,保证计数不会跌到负数。
在请求拦截器里调用 showLoading,在响应拦截器里调用 hideLoading,要注意成功和失败分支都必须调用,否则请求一旦失败,计数器不会减少,全屏 loading 就会一直卡着。这个“错误分支忘减计数”的坑,几乎每月都能在一些新手代码里看到。
complete 用 finally 更稳。不过如果用了 axios 的拦截器,没有原生 finally,所以要在成功分支和失败分支分别调用 hideLoading。
另外我建议给每个请求开放一个开关:config.loading = false 可以跳过全局 loading。比如文件上传的进度条有自己的 UI,就不需要全屏 loading;轮询接口也不适合每次都弹全屏 loading。这个开关在后续完整代码里会体现。
5. GET 请求缓存:内存 Map + 过期时间
5.1 什么时候该用缓存
项目里总有那么几个接口数据不怎么变,却被反复请求:比如字典数据、省市区列表、当前用户信息。这类接口放在页面 onMounted 里加载一次,切页后又要加载一次。与其让后端承受无意义的查询压力,不如在 axios 封装层做一层轻量内存缓存。
缓存的粒度要把握好:只缓存 GET 请求,因为 GET 是幂等查询,数据一致性风险相对低;POST、PUT、DELETE 都不缓存,业务上这些请求通常涉及数据变更,缓存脏数据会带来大事故。另外缓存要支持配置开关,因为有些 GET 接口是实时数据(比如今日订单量),缓存了就是灾难。
5.2 缓存模块实现
内存缓存的优点是快,缺点是刷新页面就没了。如果希望跨会话保留,可以把缓存存到 sessionStorage,但需要处理序列化、反序列化和版本失效问题,复杂度会高不少。中小项目用内存缓存就够了,刷新后无非是多请求一次后端,完全可以接受。
接入 axios 时,关键在于“命中缓存就不要再发请求了”。这需要在请求拦截器阶段就判断:如果这个请求的指纹在缓存里,就直接构造一个假的 Promise 返回。但 axios 拦截器里返回的 config 会被当成请求配置继续发网络请求,所以必须在请求拦截器就分流。
用 reject 故意走错误分支,然后在响应拦截器失败分支里检测到 CACHE_HIT 标记,把数据正常返回。这个 trick 有点绕,我一开始也觉得很 hack,但它在 axios 的拦截器模型下是最简洁的实现方式。实现时用一个业务自定义的错误对象形状,不要影响正常错误逻辑。
5.3 手动刷新与缓存强制跳过
缓存最怕的就是数据更新了,前端还在用旧缓存。解决思路是给请求方一个“强制不走缓存”的开关,调用 request 时传 options = { force: true },请求拦截器看到 force 就跳过缓存判断。
在请求拦截器里:if (config.force) 直接跳到正常逻辑,不走缓存判断。下拉刷新、用户手动点击“刷新”按钮的场景,一定要带上 force,这是缓存设计里最容易漏掉的一环。我真的见过团队上线后反馈“数据不更新”,排查半天发现是缓存开关没做强制刷新出口。
6. 统一错误处理:HTTP 错误和业务错误分开处理
6.1 错误的两层概念
错误处理首先要分清楚两层错误:
第一层是 HTTP 层错误,指网络层面没走通:断网、超时、404、500、502 等。这层错误由 axios 的错误分支捕获,错误对象的 error.response.status 可以拿到状态码。
第二层是业务层错误,指 HTTP 200 返回了,但后端在 body 里告诉你说“这笔订单不存在”“库存不足”之类。不同项目结构不一样,有的后端返回 { code: 0, data, msg },有的返回 { success: true, data, message },我在代码注释里写了适配。
6.2 错误映射和提示
先准备一张 HTTP 状态码映射表,把 400、401、403、404、500、502、503、504 这些高频状态码映射成用户能看懂的中文提示。
响应拦截器的错误分支里,从 error.response?.status 取状态码,优先用映射表,映射不到就回退到 error.message 或“网络异常,请稍后重试”。
业务码处理则放在成功分支:如果响应体是 { code: 0, ... } 这种结构且 code !== 0,就要按业务失败处理。注意这里不要和 HTTP 状态码混为一谈,一个走成功分支,一个走失败分支。
7. 请求重试:指数退避,只在值得重试时重试
7.1 什么请求能重试,什么绝对不能重试
请求重试是把双刃剑,重试可以救回一次网络抖动,但也可能造成灾难。核心规则第一条:只有幂等请求可以重试。GET、PUT、DELETE 是幂等的,多次执行结果一致,可以重试;POST 不是幂等的,用户提交订单时网络超时,你自动重试一次,可能就下了两单。
所以重试默认只对 GET 开启,其他方法需要显式配置 retry 为 true 才开启。
第二条规则:不是所有错误都值得重试。网络超时(ECONNABORTED)、5xx 服务端错误值得重试;4xx 客户端错误(参数错误、权限不足)重试一万次也没用,就别浪费时间。判断条件放在 shouldRetry 函数里。
7.2 指数退避的实现
指数退避的意思是每次重试的等待时间呈指数增长:第一次等 0.5s,第二次 1s,第三次 2s,这样既给了服务端恢复的时间,又不至于在故障期间疯狂重试压垮后端。
重试的核心逻辑放在响应拦截器失败分支的最前面:如果 shouldRetry 返回 true,就把 config.retryCount 加一,然后等待 2^retryCount * RETRY_DELAY 毫秒,再调用 service(config) 重发原请求。
这里有一个很多人没注意到的细节:重试时直接调用 service(config),会再次进入请求拦截器,重新走一遍 addPending、loading、缓存判断逻辑。如果之前的 pending 记录没清除,重试请求可能被自己取消或误伤。所以在 setTimeout 之前先 removePending(config),确保指纹是干净的。这也是我在排查“重试后一直失败”问题时最终发现的根因。
8. 完整封装代码:可直接复制到项目的 request.js
8.1 依赖和目录
先准备好依赖。下面这份完整代码我用的是 element-plus 的消息和 Loading 组件,如果你项目用的是 antd、vant 或原生实现,把对应的 import 替换掉即可。核心是 axios、qs 这两个依赖。
目录结构建议这样放,把职责拆开,后续维护会轻松很多:
8.2 完整代码(逐行注释)
下面这份代码就是完整的 request.js,我把前面各章的逻辑全部整合在一起。为了方便复制,我尽可能把注释写完整。
这份代码有个小问题需要说明:isRefreshing 和 waitQueue 定义在了响应拦截器内部,每次进入 401 分支时都会重新创建,其实达不到“全局锁”的效果。实际使用时应该把它们提到 service 外层,和 handleRetry 一样是模块级状态。我理解你的意思。让我整理一下:把 isRefreshing 和 waitQueue 提升到模块顶层,并且把 401 处理逻辑单独封装成函数。我会在正式文章中修正这一点。
现在我需要继续整理后续内容,包括问题速查表和个人经验总结。
在实际发布的博文中,我会在完整代码里把 isRefreshing、waitQueue 提升到模块顶部。这也是一个很好的“坑”分享点——你写完代码自以为处理了并发刷新,结果把状态定义在拦截器函数内部,根本没生效。这种坑只有实践过才会发现。
我需要重新回忆或改进一下:在给出的完整代码中,确实应该定义在顶部。我会修正为:
模块顶部:
然后再写 401 分支时使用它们。在完整代码中我会直接这么写,并且加注释说明为什么定义在顶层。
为了不过度重复,正式博文中第 8 节的完整代码里就已经包含了这种正确写法。
好,现在继续写后续章节,确保达到 5000 字以上。
9. 实战中的坑与问题速查表
9.1 高频问题排查表
表格列举问题和解决思路。
| 现象 | 根因 | 解决方案 |
|---|---|---|
| 取消请求后一直弹“请求被取消” | 没判断 axios.isCancel | 在错误分支先判断 isCancel,主动取消的请求不弹提示 |
| 上传文件时后端收不到文件 | 手动设置了 Content-Type | FormData 场景下 delete headers 里的 Content-Type |
| 快速切换分页,页面数据错乱 | 没有取消旧请求,最后一次返回的可能是旧数据 | 用 AbortController 取消旧请求,或用请求序号丢弃过期响应 |
| 全屏 loading 一直转 | 错误分支没有调用 hideLoading | 成功和失败分支都调用 hideLoading,用计数保护 |
| token 刷新时并发请求全部报 401 | 每个 401 各自刷新 token | 用 isRefreshing 全局标志 + waitQueue 等待队列 |
| 重试后接口仍失败 | 重试请求被 pending 拦截,或者重新走了缓存 | 重试前 removePending,缓存开启时也要注意 |
| 缓存的数据一直不更新 | 缓存缺少强制刷新出口 | 提供 force 选项,手动刷新时跳过缓存 |
9.2 其他经验教训
关于重试和缓存的结合:如果 GET 请求缓存开启,第一次请求失败后重试,重试请求可能会命中缓存,返回缓存数据。这在业务上可能造成“失败后重试拿到的还是旧数据”的困惑。建议 GET 请求开启重试时,重试不要走缓存,或者在重试 config 上设置 force: true。
关于 loading 的粒度:全局 loading 适合页面跳转、表单提交这些整体反馈场景,但表格局部刷新配全屏 loading 会感觉页面卡死,这种情况下建议业务层调用封装的局部 loading 或自己控制。封装时给每个请求加 config.loading = false 开关是我强烈建议的设计。
10. 结尾
个人体会收尾。
好,我把这些组织成一篇完整流畅的博文输出。注意文字要自然,段落要足够。虽然我的规划里有些章节号是 9、10,但按照 H2/H3 编号规范来。
让我估算一下字数:代码部分很长,加上解释文字,全文应该会超过 5000 字。现在开始正式写作,注意所有文案要求。
关于一些细节(如 qs 的 sort 参数写法),让我确认一下:qs.stringify(params, { sort: (a, b) => a.localeCompare(b) }) 是有效的,会按 key 排序。对于 data 为字符串或 FormData 的情况,qs.stringify 也能处理;不过 FormData 本身无法用 qs 序列化,在实际代码里 data instanceof FormData 时应该特殊处理,避免生成错误的指纹。我可以在正文中补充:如果 data 是 FormData,序列化部分可以跳过用表单转字符串,或者说指纹里只包含方法+URL+params,data 部分为了防重复可能不精确。为避免误导,在完整代码里我应该写个防御性判断:typeof data === 'string' 就用原文,否则 qs.stringify。但实际中 FormData 重复请求很少见,上传文件一般不会防重复。我可以保持简单并在文中注释说明“FormData 或流式数据不好序列化,这种情况直接跳过 data 指纹即可”,这样是诚实和实用的。
为了保持代码简洁,我可以写成:
这个更稳妥。我会在完整代码里用这个版本。
再想想 baseURL 的 import.meta.env.VITE_API_BASE_URL —— 如果读者用 CRA 或 webpack,应该是 process.env.REACT_APP_API_BASE_URL。为了让通用性更强,我可以写成:
不过 process.env 在 build 时可能不存在,简单点就保留 import.meta.env 并在注释里说明,也可以不写环境变量直接 '/api'。我选择简单为主,用注释提示适配。
关于 401 刷新里调 service(error.config),此时 error.config 可能已经被改过(比如 abort signal 可能已触发),重放时应该重新 create service。不过这属于细节,我保持说明:重放请求时注意 config 中 signal 可能已经被置为已取消状态,需要删除 config.signal 让 axios 重建。这个我可以加进去:在重放前 delete error.config.signal。这个点很实用,我加进去。
还有缓存命中用 reject 的 hack,在响应拦截器失败分支里返回 Promise.resolve(error.data)。如果其他拦截器(比如业务自己在响应成功里也拦截)会怎样?我这里只在请求拦截器和响应拦截器处理,问题不大。我会在代码注释中说明这种 hack 的用途。
内容已经规划得很充实,开始写作。注意输出的唯一正文不能有前置说明和后置元信息。
我要留意不要过度使用列表。适当用列表、表格、代码块。段落至少150字。
开始正式输出。前端项目只要稍微有点规模,axios 二次封装就是躲不开的一步。很多朋友一开始图省事,直接在页面里 axios.get,等接口数量多起来、鉴权逻辑和错误处理铺开之后,代码就彻底失控了。我这次把自己的一份完整封装方案分享出来,涵盖鉴权、重复请求拦截、全局 Loading、GET 缓存、统一错误处理和请求重试这六块能力,全代码带逐行注释。文章里不只有可以直接抄的代码,还会把每个功能为什么这样做、哪些地方容易踩坑都讲清楚。不管你是刚开始接触前端工程化的新人,还是想把现有封装再规范一把的老手,这份合集应该都能给你一些参考。
1. 封装前先想明白:你要的到底是哪六样能力
1.1 二封的本质是统一入口,不是代码洁癖
有人把 axios 二次封装理解成“代码写得好不好看”的问题,我见过最夸张的团队,封装只是为了少写几行重复的 baseURL。其实二封的本质,是把“每个请求都要处理一遍”的横切逻辑收拢到一个统一入口。想象一下,你项目里有 20 个页面,每个页面都直接调 axios,那么鉴权怎么加?每个页面都要从 localStorage 取 token 塞 header。错误提示怎么弹?每个页面都要判断一遍 status,弹各自风格的提示。loading 怎么控制?每个组件维护自己的 loading boolean,页面一多全是重复代码。
封装的核心,就是通过 axios 的拦截器机制,把鉴权、错误提示、loading、缓存、防重复、重试这些横切关注点集中实现。业务代码里只需要调用一个 request 方法,传 url 和参数,拿回数据就行。这相当于给所有请求建了一个统一的“安检通道”,每个请求流量进来都要走同一套流程。一线开发者的直觉应该都类似:什么时候该意识到要封装?当你发现自己开始复制粘贴第一段 .then 逻辑的时候,就该停下来把封装做了。
1.2 六项能力怎么取舍
我见过不少项目把封装做得特别花哨,什么权限判断、埋点上报、接口监控全塞进去,结果封装层越写越复杂,团队里没人敢动。但真正的核心能力,其实就这六样:
| 能力 | 解决的真实问题 | 不做的代价 |
|---|---|---|
| 鉴权(token + 401 处理) | 每个请求都要带 token,过期后要统一处理 | 每个页面手动塞 token,401 后乱跳登录或被并发刷新打爆 |
| 重复请求拦截 | 用户快速点击查询/提交,连续发同一个请求 | 重复下单、重复查询,后端压力大,前端数据互相覆盖 |
| 全局 Loading 控制 | 请求期间需要统一的加载反馈 | 每个组件各写各的 loading,并发时闪屏或永远关不掉 |
| GET 请求缓存 | 短时间内反复查询相同数据 | 重复请求同一个接口,浪费流量、拖慢页面 |
| 统一错误处理 | 后端返回各种错误码和网络异常 | 每个页面 try/catch 一堆,提示风格不统一 |
| 请求重试 | 网络抖动、服务端瞬间 5xx | 用户手动刷新,故障恢复慢、体验差 |
这六项的共性在于:规则明确、全局一致。只要逻辑是全局一致的,就不应该散落在业务代码里。这也是我建议封装边界就停在 HTTP 层的原因,带业务属性的逻辑(比如某个模块的特殊权限判断)应该放在业务层,别在封装里混合,不然后期维护真的会痛苦。
2. 鉴权模块:请求拦截器是放 token 的第一现场
2.1 token 的存取:localStorage 还是内存变量
鉴权是封装里最基础的一块。token 存哪,主流方案无非 localStorage、cookie、Pinia 或 Vuex。我习惯“双写”:localStorage 持久化一份,保证页面刷新后登录态不丢;内存变量再存一份,避免每次请求都去 JSON.parse localStorage。高频接口轮询的时候,这个细节虽然不起眼,但数据量大了还是有区别的。
这里有个容易被忽略的点:刷新页面后,localStorage 里的 token 需要被恢复到内存变量里。我的做法很简单,项目入口处初始化一次 getToken(),把值拉进内存。如果你用了状态管理库,可以在 store 里维护一个 user.token,加载初始值的时候也做一次恢复。总之“双写”这套思路的核心,是不让每个请求都变成一次 localStorage 的读操作。
2.2 请求拦截器:在请求发出前把 token 放进 header
axios 的请求拦截器是执行 request(config) 之后、真正发出网络请求之前触发的,这是加鉴权头的最佳位置。每个请求都会先经过这里,token 只需判断一次,业务代码完全不用关心 header 的事。
很多封装踩坑都踩在 FormData 上。axios 默认情况下,传普通对象会序列化成 JSON 并设置 application/json;传 FormData 则自动识别为 multipart/form-data 并生成 boundary。但如果你的请求拦截器里无脑写了 config.headers['Content-Type'] = 'application/json',文件上传就直接废了。所以我用 instanceof FormData 判断,一旦识别到 FormData,就删除手动设置的 Content-Type,让浏览器接管。
2.3 响应拦截器遇到 401:并发刷新 token 的等待队列
token 终归是有过期时间的,过了期后端会返回 401。最粗糙的做法是弹个“登录过期”然后跳登录页,但这在并发场景下会出大事:一个页面同时发 3 个请求,3 个 token 都过期了,会同时触发 3 次跳登录,刷新 token 接口也会被同时调用好几次,后端大概率会限流,体验非常糟。
正确的做法是用一个全局标志位 + 等待队列:第一个 401 触发刷新流程,后续 401 不重复刷新,而是进入队列等待,刷新完成后再用新 token 重放这些请求。这里最关键的是 isRefreshing 和 waitQueue 必须定义在模块顶层,不能定义在响应拦截器回调内部,否则每次进入回调都会重新创建,锁就失效了。这个坑我自己踩过,看似写了队列,实际上状态全被重置,等于没写。
重放时要用 service(config) 而不是直接 axios,这样会重新走一遍拦截器,鉴权、防重复逻辑都会正常执行。另一处细节是 delete config.signal,因为初次请求可能配了 AbortController 的 signal,401 失败后被置为已取消,重放前不清掉会导致请求还没发出去就被取消。
3. 重复请求拦截:别让用户手滑点出两个订单
3.1 什么请求才算“重复”
重复请求拦截,说直白点就是防抖和幂等在请求层的统一实现。用户快速双击一个“提交订单”按钮,如果后端没有做幂等,就会下两单;表格快速切分页时,上一请求还没回来,下一次请求又发出去了,响应顺序一乱,页面数据就会被覆盖。这些问题都可以通过请求层的指纹判断解决。
判断“重复”要给请求生成一个指纹。指纹的特征必须能唯一标识一个请求:method、url、params、data 都一样,那就是同一个请求。这里有个大坑:直接用 JSON.stringify(config.params) 生成指纹,一旦对象里面键的顺序变了(比如一个地方传 { id: 1, type: 2 },另一个地方传 { type: 2, id: 1 }),JSON.stringify 的结果就不同,同一个请求会被误判成两个请求。所以这里我用了 qs 库,并且给序列化函数加上排序参数。
注意这里把 FormData 单独处理了。FormData 的内部结构没法用 qs 稳定序列化,所以用固定字符串标记。这样避免上传文件时每次指纹都不同导致防重复失效,也避免序列化行为不一致。
3.2 用 AbortController 取消旧请求,不用过时的 CancelToken
axios 老版本支援 CancelToken,但官方后来推荐用浏览器标准的 AbortController。原理很简单:创建 AbortController 实例,把 signal 传给 axios 的 config,外部调用 controller.abort() 就能取消这个请求。实现防重复时,我们用 Map 保存每个请求的指纹和 controller。
这套方案默认采用“取消旧请求、保留新请求”的策略。为什么要这样?因为用户在搜索框快速输入关键词时,我们希望最终响应的是最后一次请求的结果,而不是第一次的。反过来,订单提交按钮更适合“保留第一次、取消后续重复”的策略,但这种场景更推荐直接用按钮防止连点,或者在后端做幂等处理。请求层的防重复主要解决的是同参并发问题,所以用“新请求取消旧请求”是默认合理的选择。
3.3 拦截器里自动挂载与清理
有了 addPending 和 removePending,接下来要做的就是在请求拦截器里记录,在响应拦截器里清理。值得注意的一点是:取消请求后 axios 会抛 CanceledError,这个错误不能走到统一错误提示里,否则每次取消一个请求就会弹一次“请求被取消”,页面还没用呢就先把用户烦死了。
axios.isCancel 专门判断请求是否被主动取消。很多封装漏掉这个判断,导致快速切分页时不停弹错误框,体验很糟。另一个细节是清理 pending 要放在 response.config 上,因为响应拦截器里拿到的 response.config 就是原始请求的 config,响应成功和失败分支都要调用 removePending,否则 Map 里会残留脏数据,内存只增不减。
4. Loading 全局控制:计数器是防闪屏和防卡死的钥匙
4.1 为什么单独开一个 loading 模块
请求期间给用户一个 loading 反馈,是最基础的用户体验要求。但 loading 放在业务组件里的话,每个页面都要维护 loading state,而且几个请求并发时,一个完成就关掉 loading,其他请求还在飞,用户会看到 loading 闪一下又消失,非常难受。
把 loading 收进封装层之后,业务代码里连 loading 变量都不用声明。但要真正做好,必须解决两件事:第一是并发计数,多个请求同时进行时,只有所有请求都结束了才关闭 loading;第二是防闪屏,有些接口 100ms 就返回了,全屏 loading 闪一下,比不显示更打扰用户。解法是延迟显示,比如 300ms 的定时器,请求在 300ms 内返回就不显示 loading,超过 300ms 才真正弹出来。
4.2 Loading 模块实现
注意 count 的兜底判断。如果因为异常分支没调用 hideLoading,loadingCount 可能出现负数,然后计数逻辑彻底错乱。我在 hideLoading 开头加了范围保护,宁可漏掉一次也不让计数变负数。即便如此,调用位置也很重要:成功和失败分支都要调用 hideLoading。我在实际项目里见过最典型的问题,就是成功分支关了 loading、失败分支忘了关,结果一个接口报错,全屏 loading 就永远转下去,用户只能刷新页面。
每个请求还要有跳过 loading 的开关,比如文件上传已经有自己的进度条,轮询接口也不需要全屏 loading。我建议的做法是判断 config.loading !== false,这样业务侧传 { loading: false } 时能跳过全局 loading。
5. GET 请求缓存:内存 Map + 过期时间
5.1 什么样的接口值得缓存
项目里总有那么几个接口数据不怎么变、却被反复请求。字典数据、省市区列表、当前用户信息都是典型例子。与其让后端承受无意义的查询压力,不如在 axios 封装层做一层轻量内存缓存。缓存的粒度要把握住:只缓存 GET 请求,因为 GET 是幂等查询,数据一致性风险相对低;POST、PUT、DELETE 都不缓存,这些请求通常涉及数据变更,缓存脏数据会造成大事故。
还有一类 GET 接口不能缓存,比如实时库存、今日订单量。这种场景下必须给请求方一个强制跳过缓存的开关。封装层提供一个 options.force,请求拦截器看到 force 就跳过缓存判断,手动刷新数据时带上 force 一定能拿到新数据。这个“强制刷新出口”是缓存设计里最容易被漏掉的,我见过团队上线后反馈数据不更新,排查半天发现是缓存没有刷新通道。
5.2 缓存模块实现
内存缓存的优点是快,刷新页面就没了。如果你需要跨会话保留,可以改成 sessionStorage 或 localStorage,但会引入序列化、过期清理、版本失效等额外复杂度。中小项目用内存缓存就够,刷新后顶多让后端多处理一次请求,完全可以接受。用了缓存之后还要格外小心:如果后端数据在客户端缓存期间被别的渠道修改了,前端拿到的还是旧数据,所以在需要实时性的接口上一定要让业务侧主动传 force。
5.3 缓存命中怎么绕过网络请求
缓存命中时不应该再发网络请求,但 axios 拦截器里返回的 config 会被继续当成请求配置去执行,所以必须在请求拦截器阶段就分流。比较巧妙的做法是:命中缓存时 reject 一个带有标记的错误对象,然后在响应拦截器的失败分支里识别这个标记,直接返回缓存数据。有点 hack,但它是 axios 拦截器模型下非常简洁的实现方式。
响应拦截器失败分支的开头就要判断:
这个实现要求自定义一个特殊形状的错误对象,同时必须放在所有统一错误处理逻辑之前,不然缓存命中也会被当成真正的错误弹提示。我在团队 code review 里也推广过这个模式,大家一开始觉得绕,但理解了拦截器模型的思路后都觉得很好用。
6. 统一错误处理:HTTP 错误和业务错误分开处理
6.1 错误必须分层,否则提示就会误导用户
说的直白一点,前端拿到错误至少有两种:网络层/HTTP 层错误,比如断网、超时、404、500;业务层错误,比如 HTTP 200 返回了,但 response body 里 code 是 1,msg 是“库存不足”。很多封装只处理了一层,结果 HTTP 200 但业务失败时,前端照样把状态码判断成成功,用户根本看不到错误提示。
响应拦截器的成功分支负责判断业务结构。不同后端的返回结构不一样,我按最常见的 { code, data, msg } 写了适配。成功分支拿到 res.code === 0 时返回 res.data;code 非 0 时弹出 res.msg 并 reject。如果你的后端是 { success, data, message } 这类结构,把判断条件换成对应的字段即可。
6.2 HTTP 状态码映射和网络异常兜底
先准备一张包含高频状态码的中文提示映射表。前端团队里最容易忽略的是 502、503、504 这些“服务端在抽风”的状态码,没有映射的时候 error.message 往往是英文,用户根本看不懂。映射表补上之后,至少用户知道是服务端出了问题,而不是怀疑自己网络欠费。
在失败分支里,取 error.response?.status,优先查映射表,查不到再用 error.message,再没有就兜底“网络异常,请稍后重试”。这样设计顺序的意义在于:映射表文案是面向用户的,error.message 可能包含英文技术信息,只能在没有映射时作为过渡展示。
7. 请求重试:指数退避,只在值得重试时重试
7.1 什么请求能重试,什么绝对不能重试
请求重试是把双刃剑,用好了能在网络抖动时自动挽救一次请求,用坏了就是灾难放大器。第一条铁律:只有幂等请求可以重试。GET、PUT、DELETE 多次执行结果一致,可以重试;POST 不幂等,比如用户提交订单时网络超时,你自动重试一次,可能就下了两单。所以封装里默认只有 GET 请求才重试,POST 需要业务方显式配置 retry: true 才开启。
第二条铁律:不是所有错误都值得重试。4xx 客户端错误,重试一万次也一样失败,比如参数错误、权限不足,这些不该浪费时间。值得重试的是网络超时(错误码 ECONNABORTED)和服务端 5xx,因为这两种情况往往是瞬时故障,重试有较大概率成功。这些判断全部收敛到 shouldRetry 函数里,一目了然。
7.2 指数退避的实现
指数退避指每次重试的等待时间呈指数增长:第一次等 0.5 秒,第二次等 1 秒,第三次等 2 秒。这样既不浪费用户的等待时间,又不至于在服务端故障期间疯狂重试导致雪上加霜。
这里有个很容易掉进去的坑:service(config) 会再次进入请求拦截器,重新走一遍 addPending、缓存判断。如果之前的 pending 记录没有清掉,重试请求会被当成“重复请求”给自己的旧请求取消掉。所以 setTimeout 之前先 removePending(config),确保指纹干净。这个坑我在一个高并发项目里排查了很久,最终发现所有重试都失败,是因为 pendingMap 里还留着上一次的 controller。
另外重试和缓存要配合好。GET 请求如果没有设置 force,重试时有可能会命中缓存,返回的是旧数据。如果业务上接受最近 1 分钟的缓存数据倒无所谓,不能接受的话,重试时在 config 上强制 force: true。
8. 完整封装代码:可直接复制到项目的 request.js
8.1 依赖和目录
先准备好依赖。这份完整代码我基于 element-plus 实现消息提示和 Loading,如果你的项目用 antd、vant 或原生写,把对应 import 替换掉即可。核心依赖是 axios 和 qs。
建议按下面的方式组织文件,把职责拆开,后续维护会轻松不少:
8.2 完整代码(逐行注释)
下面就是整合了上述所有能力的 request.js 完整代码。为了方便复制,我把注释写在代码块里,每个关键点都尽量解释清楚。