Axios 二次封装：拦截器、统一错误处理与文件下载

Axios 二次封装拦截器、统一错误处理与文件下载前端项目一旦接口多起来就会出现这些痛点每个请求都要手动带 token401/500 的处理散落在各个页面文件下载Excel处理不统一兼容性一堆坑这篇给你一套可复用、可维护、能直接落地到业务项目里的 Axios 二次封装思路请求实例把 baseURL/timeout/header 做成统一入口拦截器Token 注入、返回结构归一、错误提示、登录失效跳转下载能力Blob 直通 文件名解析 “失败时返回 JSON”兼容文中示例会对齐一份典型的工程实现与你项目frontend/vue/src/api/request.js的处理方式一致Token 以Authorization: Bearer token方式注入config.silent控制是否弹出错误提示responseTypeblob/arraybuffer直接返回原始响应兼容{ success, message, data }与{ code, message, data }两种返回业务code ! 200统一当作失败处理0. 先定“契约”你希望页面拿到什么做封装前先把“页面能依赖的返回契约”定下来否则项目后期会出现有的接口返回{ code, message, data }有的接口返回{ success, message, data }有的接口直接返回数组最终导致每个页面都在写 if-else 兼容错误提示风格不一致建议你把页面层的依赖收敛为成功返回{ code: 200, message, data }或直接返回data但要统一失败Promise 直接 reject页面只写一个 catch 就能兜底1. 为什么需要二次封装你希望达到的效果所有请求默认带上公共配置baseURL、timeouttoken 注入、错误提示、登录失效处理集中在一处页面只关心“业务成功/失败”而不是关心 HTTP 细节2. 创建实例把环境差异和默认 header 固化工程里最常见的 baseURL 策略开发环境走代理baseURL 为空生产环境走真实域名通过环境变量配置同时统一 Content-Type避免每个请求都写一遍。一个可参考的实例骨架与项目里常见写法一致importaxiosfromaxiosconstserviceaxios.create({baseURL:import.meta.env.DEV?:(import.meta.env.VITE_API_BASE_URL||http://localhost:8080),timeout:10000,headers:{Content-Type:application/json;charsetUTF-8}})3. 请求拦截器统一注入 tokenservice.interceptors.request.use((config){consttokengetToken()if(token)config.headers.AuthorizationBearer${token}returnconfig})注意点不要在每个 API 函数里重复拼 headertoken 的读取来源建议是 storePinia 持久化兜底工程建议Token 缺失要允许请求继续发例如登录接口本来就不需要 token不要在请求拦截器里做业务提示提示应尽量收敛在响应拦截器4. 响应拦截器三类返回要分开处理响应拦截器建议先把返回分为三类下载类responseTypeblob/arraybuffer直接返回原始response业务类JSON 返回走“结构归一 code 判定”异常类HTTP 状态码异常、网络异常常见后端返回HTTP 200但code ! 0表示业务失败你可以在拦截器里统一收敛下面给一份“能直接抄到项目里”的完整骨架与常见 Vue3 Element Plus Pinia 的组合一致import{ElMessage}fromelement-plusimportrouterfrom/routerimport{useUserStore}from/store/modules/userfunctionhandleLogoutAndRedirect(){if(import.meta.env.DEV)returnconstuserStoreuseUserStore()userStore.logout()router.push(/auth/login)}functionnormalizeHttpErrorMessage(error){if(error.response){switch(error.response.status){case401:return未授权请重新登录case403:return拒绝访问case404:return请求错误未找到该资源case500:return服务器错误default:return连接错误${error.response.status}}}if(error.request)return网络连接失败请检查网络return请求失败}service.interceptors.response.use((response){// 文件下载blob/arraybuffer直接返回原始响应不走统一 code 判断constrtresponse.config?.responseTypeif(rtblob||rtarraybuffer){returnresponse}constresresponse.dataconstsilent!!response.config?.silent// 兼容部分接口返回{ success: boolean, message, data }if(restypeofresobjecttypeofres.codeundefinedtypeofres.successboolean){return{code:res.success?200:500,message:res.message,data:res.data}}if(res.code!200){if(!silent){ElMessage.error(res.message||请求失败)}if(res.code401){handleLogoutAndRedirect()}returnPromise.reject(newError(res.message||请求失败))}returnres},(error){constsilent!!error?.config?.silentconstmessagenormalizeHttpErrorMessage(error)if(!silent){ElMessage.error(message)}if(error.response?.status401){handleLogoutAndRedirect()}returnPromise.reject(error)})关键点页面只处理 Promise reject不要再关心 code401 逻辑务必统一否则体验会很割裂落地建议很重要弹窗提示要可控列表页自动刷新、轮询接口失败不应该一直弹框所以需要silent这种开关登录失效要防“开发环境误踢”开发环境经常没开完整登录链路建议按环境判断是否强制跳转5. 文件下载一套完整的“可复用”方案文件下载看似简单但坑通常集中在三点返回是 Blob你却按 JSON 处理文件名在Content-Disposition里需要解析与解码后端失败时仍然返回 JSON但 responseType 是 blob前端要能把错误信息读出来常见坑后端返回的是 blob但你按 JSON 解析会报错下载文件名在 header 里需要解码请求侧下载接口设置responseType: blobexportfunctionexportExcel(params){returninstance.get(/xxx/export,{params,responseType:blob,})}响应侧从 header 获取文件名创建临时 a 标签触发下载functiondownloadBlob(blob,filename){consturlwindow.URL.createObjectURL(blob)constadocument.createElement(a)a.hrefurl a.downloadfilename a.click()window.URL.revokeObjectURL(url)}如果后端在下载失败时返回 JSON错误信息你需要兼容blob 转 text - JSON.parse 判断是否是错误给一份可直接复用的工具函数示例functiongetFilenameFromDisposition(disposition){if(!disposition)returnconstmatch/filename\*UTF-8([^;])|filename?([^;])?/i.exec(disposition)constrawmatch?.[1]||match?.[2]||try{returndecodeURIComponent(raw)}catch(e){returnraw}}asyncfunctiontryParseBlobAsJson(blob){try{consttextawaitblob.text()returnJSON.parse(text)}catch(e){returnnull}}exportasyncfunctiondownloadByResponse(response,fallbackNameexport.xlsx){constblobresponse.dataconstcontentTyperesponse.headers?.[content-type]||// 后端失败时返回 JSON但前端按 blob 接收需要把错误信息读出来if(contentType.includes(application/json)){constjsonawaittryParseBlobAsJson(blob)constmsgjson?.message||json?.msg||导出失败thrownewError(msg)}constdispositionresponse.headers?.[content-disposition]constfilenamegetFilenameFromDisposition(disposition)||fallbackNameconsturlwindow.URL.createObjectURL(blob)constadocument.createElement(a)a.hrefurl a.downloadfilename a.click()window.URL.revokeObjectURL(url)}工程化建议把“解析文件名 下载 失败解析”封装成downloadByResponse(response)下载接口统一返回 Axios 的原始响应因为你要拿 headers6. 常见工程增强可选但很加分6.1 请求取消与防抖列表页常见场景关键字搜索、快速切换筛选条件你可以用AbortController取消上一次请求或在输入侧做防抖更推荐6.2 统一重试与降级谨慎使用对“幂等查询接口”可以在网络抖动时做少量重试但要避免把后端瞬时故障放大成雪崩让用户以为操作成功但其实重复请求7. 排查清单封装后出了问题怎么定位Token 没带上看请求头是否包含Authorization: Bearer ...页面拿到的不是 data确认响应拦截器最终返回了什么是否返回res还是res.data下载得到一个很小的文件通常是后端返回了错误 JSON被当成文件保存了需要做 blob-text 解析判断一直弹错误给轮询/静默接口加silent: true开发环境频繁被踢登录确认是否对 DEV 做了“401 不强制跳转”的处理8. 总结Axios 二次封装的核心是把“通用横切逻辑”从页面里剥离请求拦截器统一注入Bearer Token响应拦截器先分流下载直通 / 业务归一 / 异常兜底再统一处理code与 401通过silent把“是否提示错误”变成可控开关下载接口返回原始响应统一做文件名解析与错误 JSON 兼容