前端手记（二）：Axios 封装与 FastAPI 联调

所属项目面向全场景用药安全的医师助手 Agent团队ColdX · 山东大学软件学院 2026年春季项目实训个人分工前端开发 界面设计目录一、背景说明二、Axios 封装设计2.1 实例化与基础配置2.2 请求拦截器2.3 响应拦截器三、接口封装四、联调中的关键问题4.1 CORS 预检失败4.2 字段命名不一致4.3 请求超时五、与 Pinia 的协作模式六、小结相关链接一、背景说明上篇确定了技术栈Vue 3 Pinia Vite。后端使用 FastAPI前端通过 HTTP 请求调用 Agent 接口。首先需要落地的是网络层。表面上只是封装 Axios 并配置拦截器但在实际联调过程中遇到了一些非预期问题其中一部分甚至来自协作层面。本文记录 Axios 封装过程及与 FastAPI 联调时的关键问题与解决方案。二、Axios 封装设计2.1 实例化与基础配置文件src/api/request.jsimportaxiosfromaxiosconstrequestaxios.create({baseURL:import.meta.env.VITE_API_BASE_URL||/api,timeout:30000,headers:{Content-Type:application/json,},})exportdefaultrequest环境变量配置.env.developmentVITE_API_BASE_URL/api配合vite.config.js中的代理配置可以避免在前端硬编码后端地址。2.2 请求拦截器功能注入 token开发环境日志输出request.interceptors.request.use((config){consttokenlocalStorage.getItem(access_token)if(token){config.headers.AuthorizationBearer${token}}if(import.meta.env.DEV){console.log([Request]${config.method?.toUpperCase()}${config.url},config.data)}returnconfig},(error)Promise.reject(error))2.3 响应拦截器后端统一返回格式{code:200,message:success,data:{}}但 Agent 接口/consult直接返回业务数据因此需要区分处理。request.interceptors.response.use((response){const{config,data}responseif(config.url?.startsWith(/consult)){returndata}if(data.code!200){consterrornewError(data.message||请求失败)error.codedata.codereturnPromise.reject(error)}returndata.data},(error){if(error.codeECONNABORTED||error.message.includes(timeout)){console.error(请求超时请稍后重试)}elseif(error.response){const{status}error.responseif(status401){console.warn(未授权)}elseif(status500){console.error(服务器错误)}}returnPromise.reject(error)})三、接口封装文件src/api/consult.jsimportrequestfrom./requestexportfunctionconsult(payload){returnrequest({url:/consult,method:post,data:payload,})}示例请求参数{symptoms:患者主诉文本,patient_info:{age:45,gender:female}}四、联调中的关键问题4.1 CORS 预检失败问题前端报 CORS 错误后端声称已配置。原因使用Content-Type: application/json存在自定义 Header触发 OPTIONS 预检请求后端未正确处理 OPTIONS解决方案app.add_middleware(CORSMiddleware,allow_origins[*],allow_credentialsTrue,allow_methods[*],allow_headers[*],)4.2 字段命名不一致问题部分字段使用下划线命名部分字段使用驼峰命名前端解析失败导致页面异常解决方案与后端统一命名规范最终统一为下划线在 store 层增加字段映射防御性处理4.3 请求超时问题初始 timeout 为 10 秒Agent 推理耗时较长请求被中断解决方案timeout 调整为 30 秒增加 loading 状态提示用户五、与 Pinia 的协作模式通过 store 封装调用逻辑避免组件直接操作请求。import{consult}from/api/consultexportconstuseConsultationStoredefineStore(consultation,{actions:{asyncsubmitConsultation(payload){try{constdataawaitconsult(payload)this.processAgentResponse(data)return{success:true,status:data.status}}catch(error){console.error(会诊请求失败,error)return{success:false,error:error.message}}}}})组件使用方式conststoreuseConsultationStore()constresultawaitstore.submitConsultation({symptoms:...})这种设计将网络层完全隔离组件只关注业务状态。六、小结本文主要内容Axios 实例与拦截器设计普通接口与 Agent 接口的差异化处理接口函数封装方式三个联调问题CORS、字段规范、超时网络层与 Pinia 的协作模式当前网络层已稳定可支持后续接口扩展。相关链接项目地址https://gitee.com/aemond/innovation-training/tree/master团队博客https://blog.csdn.net/curufin/category_13140668.html