【Axios统一封装】【中后台前端接口规范】从拦截器配置到业务落地彻底搞懂API请求规范封装避开重复代码与分散错误处理坑 文章目录一、为什么要做统一封装1.1 不封装时的问题二、封装前先搞清楚这几件事2.1 请求与响应的结构2.2 常见后端约定三、完整封装示例可直接用于项目3.1 目录结构建议3.2 第一步创建 request.js 封装3.3 第二步按模块拆分 API3.4 第三步在页面中使用四、常见配置说明4.1 baseURL 的几种写法4.2 GET 用 paramsPOST 用 data4.3 请求头里传 Token 的常见方式五、常见坑与注意事项5.1 拦截器里 return 的值5.2 业务需要原始 response 时5.3 某些接口不想统一错误提示5.4 重复请求与取消六、小结封装时建议遵守的原则七、速查清单 系列模块导航同学们好我是 Eugene尤金一名多年中后台前端开发工程师。Eugene 发音 /juːˈdʒiːn/大家怎么顺口怎么叫就好很多前端开发者都会遇到一个瓶颈代码能跑但不够规范功能能实现但维护起来特别痛苦一个人写没问题一到团队协作就各种混乱、踩坑、返工。想写出干净、优雅、可维护的专业代码靠的不是天赋而是体系化的规范 真实实战经验。这一系列《前端规范实战》我会用大白话 真实业务场景不讲玄学、不堆理论只分享能直接落地的规范、标准与避坑指南。帮你从「会写代码」真正升级为「会写优质、可维护、团队级别的代码」。一、为什么要做统一封装1.1 不封装时的问题日常直接用 Axios 时代码常是这样// 项目里到处都是这样的重复代码axios.get(/api/user/info).then(res{if(res.data.code200){console.log(res.data.data)}else{Message.error(res.data.message||请求失败)}}).catch(err{Message.error(网络错误请稍后重试)})// 另一个文件里又来一遍axios.post(/api/order/create,{productId:1}).then(res{if(res.data.code200){// ...}else{Message.error(res.data.message||请求失败)}}).catch(err{Message.error(网络错误请稍后重试)})问题主要有重复逻辑code 200、错误提示、catch在几十上百个请求里反复写。风格不统一有人用res.data有人用res.data.data维护成本高。扩展困难加 token、统一 loading、请求重试等都要改很多地方。错误处理分散401 未登录、403 无权限等每个接口各自处理容易遗漏。统一封装的目的就是把这些公共逻辑集中在一处让业务代码更干净、可维护。⬆ 返回目录二、封装前先搞清楚这几件事2.1 请求与响应的结构先看一次完整请求的“路径”你的代码 axios.get(/api/user) ↓ 请求拦截器可以改请求头、加 token 等 ↓ 真正发出去的 HTTP 请求 ↓ 后端返回 ↓ 响应拦截器可以统一处理 data、错误等 ↓ 你的 .then() 里拿到的 res业务里一般期望只拿到「业务数据」而不是res.data.data这种多层结构。错误在封装层统一处理业务尽量只写「成功时做什么」。⬆ 返回目录2.2 常见后端约定很多项目都是类似约定// 成功时{code:200,message:成功,data:{id:1,name:张三}}// 失败时{code:401,message:未登录请先登录// 可能没有 data}code含义可约定为200成功401未登录403无权限500服务器错误封装时围绕这些约定来设计就能让接口调用更统一。⬆ 返回目录三、完整封装示例可直接用于项目3.1 目录结构建议src/ ├── utils/ │ └── request.js # Axios 封装 ├── api/ │ ├── user.js # 用户相关接口 │ └── order.js # 订单相关接口⬆ 返回目录3.2 第一步创建request.js封装/** * Axios 统一封装 * 职责基础配置、拦截器、统一错误处理 */importaxiosfromaxiosimport{ElMessage}fromelement-plus// 如果用 Vue3 Element Plus// 如果用 Vue2改为import { Message } from element-ui// 1. 创建 axios 实例 constrequestaxios.create({baseURL:import.meta.env.VITE_API_BASE_URL||/api,// Vue3 Vite 写法// baseURL: process.env.VUE_APP_BASE_API || /api, // Vue2 Vue CLI 写法timeout:15000,// 超时时间 15 秒headers:{Content-Type:application/json;charsetUTF-8}})// 2. 请求拦截器 request.interceptors.request.use((config){// 从本地存储获取 token按你项目的存储方式改consttokenlocalStorage.getItem(token)if(token){config.headers.AuthorizationBearer${token}}returnconfig},(error){console.error(请求拦截器出错,error)returnPromise.reject(error)})// 3. 响应拦截器 request.interceptors.response.use((response){constresresponse.data// 根据你们后端的 code 约定来写if(res.code200){// 成功只返回业务数据业务层直接用returnres.data}// 业务错误如参数错误、权限不足等ElMessage.error(res.message||请求失败)returnPromise.reject(newError(res.message||请求失败))},(error){// HTTP 错误网络错误、404、500 等if(error.response){conststatuserror.response.statusswitch(status){case401:ElMessage.error(未登录或登录已过期请重新登录)// 跳转登录页// router.push(/login)breakcase403:ElMessage.error(没有权限访问)breakcase404:ElMessage.error(请求的资源不存在)breakcase500:ElMessage.error(服务器错误请稍后重试)breakdefault:ElMessage.error(error.response.data?.message||请求失败)}}else{ElMessage.error(网络异常请检查网络连接)}returnPromise.reject(error)})exportdefaultrequest要点说明axios.create()创建独立实例不影响全局 Axios。baseURL所有请求前都会自动拼接不用在每次调用里写/api。timeout超时统一处理避免请求一直挂起。请求拦截器统一加 token、统一请求头。响应拦截器code 200时直接返回res.data业务层少一层嵌套非 200 和 HTTP 错误统一提示和reject。⬆ 返回目录3.3 第二步按模块拆分 API// api/user.jsimportrequestfrom/utils/request/** * 获取用户信息 * returns {Promise} 用户信息对象 */exportfunctiongetUserInfo(){returnrequest({url:/user/info,method:get})}/** * 更新用户资料 * param {Object} data - 用户资料 */exportfunctionupdateUserInfo(data){returnrequest({url:/user/update,method:post,data})}// api/order.jsimportrequestfrom/utils/request/** * 创建订单 * param {Object} data - 订单数据 */exportfunctioncreateOrder(data){returnrequest({url:/order/create,method:post,data})}/** * 获取订单列表 * param {Object} params - 查询参数 */exportfunctiongetOrderList(params){returnrequest({url:/order/list,method:get,params})}⬆ 返回目录3.4 第三步在页面中使用// views/UserProfile.vuescript setupimport{ref,onMounted}fromvueimport{getUserInfo,updateUserInfo}from/api/userconstuserInforef({})onMounted(async(){try{// 直接拿到业务数据不需要 res.data.datauserInfo.valueawaitgetUserInfo()}catch(err){// 错误已在拦截器里提示这里一般只需做页面级处理如清空、跳转console.log(获取用户信息失败,err)}})asyncfunctionhandleSave(){try{awaitupdateUserInfo(userInfo.value)ElMessage.success(保存成功)}catch(err){// 错误已统一处理}}/script对比不封装时不需要再写if (res.data.code 200)。不需要在.catch里重复弹错误。接口路径、环境变量都在封装层统一管理。⬆ 返回目录四、常见配置说明4.1baseURL的几种写法// 1. 开发用代理生产用真实域名baseURL:import.meta.env.VITE_API_BASE_URL// 在 .env.development 里配 /api// 2. 根据环境自动切换baseURL:import.meta.env.MODEdevelopment?/api:https://api.xxx.com// 3. 多环境// .env.development - VITE_API_BASE_URL/api// .env.production - VITE_API_BASE_URLhttps://api.xxx.com开发时通常配合 Vite/Vue CLI 的 proxy把/api转发到后端// vite.config.jsexportdefault{server:{proxy:{/api:{target:http://localhost:3000,changeOrigin:true}}}}⬆ 返回目录4.2 GET 用paramsPOST 用data// GET参数拼在 URL 上 ?id1namexxxrequest({url:/user/list,method:get,params:{id:1,name:张三}})// POST参数在请求体里request({url:/user/create,method:post,data:{name:张三,age:25}})混用会出错GET 用data不会出现在 URL 上POST 用params一般也不会被后端按请求体解析。⬆ 返回目录4.3 请求头里传 Token 的常见方式// 1. Bearer Token最常见config.headers.AuthorizationBearer${token}// 2. 自定义字段config.headers[X-Token]token// 3. 业务要求的字段名config.headers[Authorization]token// 有的后端不要 Bearer 前缀以你们后端文档为准。⬆ 返回目录五、常见坑与注意事项5.1 拦截器里return的值// ✅ 正确成功时 return 的值会作为 Promise 的 resolve 结果request.interceptors.response.use((response){returnresponse.data// 业务拿到的就是这个})// ❌ 容易出错忘了 returnrequest.interceptors.response.use((response){response.data// 没有 return业务拿到的是 undefined})⬆ 返回目录5.2 业务需要原始response时例如要读headers里的分页信息// 方案一在接口里传一个配置告诉拦截器「不要解包」// request.js 中request.interceptors.response.use((response){constresresponse.dataif(res.code200){if(response.config.returnRawResponse){returnresponse// 返回完整 response}returnres.data}// ...})// 调用时request({url:/order/list,method:get,params:{page:1},returnRawResponse:true// 自定义标记})⬆ 返回目录5.3 某些接口不想统一错误提示// 在 request.js 的响应拦截器中if(res.code!200){if(!response.config.skipErrorHandler){ElMessage.error(res.message||请求失败)}returnPromise.reject(newError(res.message||请求失败))}// 调用时request({url:/some/silent-api,method:get,skipErrorHandler:true// 不弹出错误提示})⬆ 返回目录5.4 重复请求与取消用户快速点击时可能发多次相同请求可以配合AbortController或请求去重逻辑在拦截器里统一处理这里不展开但封装时要预留扩展点。⬆ 返回目录六、小结封装时建议遵守的原则原则说明单一职责request.js只做请求封装业务逻辑放 API 和页面统一入口所有接口都通过封装的request不直接axios.xxx约定优于配置code、data结构统一减少分支判断可配置通过config支持skipErrorHandler、returnRawResponse等环境分离baseURL、timeout等用环境变量便于多环境部署⬆ 返回目录七、速查清单是否所有接口都通过封装的request调用baseURL是否按环境正确配置Token 是否在请求拦截器里统一添加成功响应是否统一返回data减少业务层解包401、403、500 等是否都有统一处理特殊接口静默失败、需要原始响应是否通过配置支持按以上方式封装后日常写业务时只需关心「调哪个接口、传什么参数」其余都交给封装层代码会更清晰、可维护。如果你有具体项目场景或报错信息可以贴出来我们可以再针对性优化封装逻辑。⬆ 返回目录 系列模块导航 API与异步请求规范一、《Axios 统一封装实战拦截器配置 baseURL 优化 接口规范避坑重复代码API 与异步请求规范篇》二、《Axios 接口请求规范实战请求参数 / 响应处理 / 异常兜底避坑中后台 API 调用混乱API 与异步请求规范篇》三、《Axios Vue 错误处理规范中后台项目实战统一捕获系统 / 业务 / 接口异常API 与异步请求规范篇》四、《前端实战Excel 导入导出规范命名 校验 错误处理 统一交互API 与异步请求规范篇》 跟着系列慢慢学把技术功底扎扎实实地打牢 系列总览「前端规范实战系列」正在持续更新中后续会整理一篇《前端规范实战系列全系列目录导航》包含每篇文章简介 直达链接方便大家按顺序、体系化学习。更新中敬请期待⬆ 返回目录技术成长从来不是比谁写得快而是比谁写得稳、规范、可维护。哪怕每次只吃透一条规范长期下来差距会非常明显。后续我会持续更新前端规范、工程化、可维护代码相关实战干货帮你告别面条代码、维护噩梦在开发与面试中更有底气。觉得有用欢迎点赞 收藏 关注不错过每一篇实战内容。我是 Eugene与你一起写规范、写优质代码我们下篇干货见