如何用FastAPI和Vue实现OpenAPI的自动契约机？

是不是每次前端联调，都觉得自己像个没有感情的“胶水工”？ 对着 Swagger 文档，把一个个接口名敲进 axios 里，再把返回值结构小心翼翼地定义成 TypeScript 类型。稍微一个字段名对不上（比如后端把 userId 改成了 userID ），页面就崩得让你怀疑人生。🎯 现在的项目，光是维护那个几百行的 api.ts 文件就耗尽了耐心。直到有一次改了一个 datetime 字段格式没更新前端，页面白屏的那一刻，我悟了——这活儿真不是人干的。 今天，作为一名饱经摧残的程序媛，我想跟你分享一个彻底告别这种“体力活”的方案。让机器去干这种重复劳动，咱们把时间留给摸鱼和解决真正的难题。

---

📌 核心摘要：这篇文章能帮你省下多少时间？ 读完这篇，你将收获一个“一键同步”的前后端协作流。 只要后端 FastAPI 代码写好，前端的 TypeScript 类型声明和接口调用函数就自动生成了。 你只需要关心业务逻辑，再也不用对着文档比对手误。 我们不止讲原理，更提供拿来即用的脚本配置。 🗺️ 内容脉络 • 第一部分：从“接口对不上”的深夜惨案说起 • 第二部分：FastAPI 给你的不只是接口，是一本“说明书” • 第三部分：在 Vue 项目里施展“无中生有”的魔法 • 第四部分：那些让你代码更香的避坑指南 💔 第一部分：从“接口对不上”的深夜惨案说起 不知道你有没有经历过这种绝望：后端说“我就改了一个字段名，很小很小的改动”。结果你前端一跑，满屏的 undefined ，控制台红得刺眼。 问题的根源在于，前后端之间缺乏一份强制的、实时的契约。口头约定靠不住，接口文档是静态的死物。我们要的是代码层面的约束力。而 OpenAPI 规范，就是来解决这个的。 ⚙️ 第二部分：FastAPI 给你的宝藏——OpenAPI 说明书 好，咱们先来聊聊原理。FastAPI 这个框架最良心的地方，就是它自带生成 OpenAPI JSON 的功能。 这就好比你去一家高级餐厅，FastAPI 不仅是那个在后厨炒菜的大厨，它还自动生成了一本实时更新的、格式标准的菜单（OpenAPI JSON）。这本菜单上清清楚楚写着：菜名叫什么（接口路径）、需要什么火候（请求方法）、要放什么配菜（请求参数）、端出来长什么样（返回数据结构）。 你可能会问：“我平时访问的那个 /docs 不就是 Swagger UI 吗？” 没错！那个漂亮的交互页面，其实就是根据这份“菜单 JSON”渲染出来的。而我们今天要做的，就是把这本菜单直接扔给前端一个“聪明的采购员”，让他自动把菜买回来（生成调用代码）。 这里千万别学我当初偷懒，在 FastAPI 里定义了 response_model 却写得马马虎虎。如果你用 Any 或者没写清楚嵌套结构，生成的 OpenAPI 就不准，前端的类型也就跟着错。务必把 Pydantic 模型写得明明白白，这是自动化的基石。 ✨ 第三部分：实战！在 Vue 项目里施展魔法 接下来重点来了，怎么把这本“菜单”变成 Vue 里能直接调用的代码？我们需要一个翻译官—— openapi-typescript-codegen 。 这个工具的选择，好比选螺丝刀，不是最贵的就好，而是要选对口的。在这个场景下，它是专门为 TypeScript 项目打磨的，生成的代码极其干净。 第一步：后端确保能导出 JSON。 启动你的 FastAPI 服务，确保访问 http://localhost:8000/openapi.json 能看到一大串 JSON 数据。 第二步：前端安装依赖并配置脚本。 在 Vue 项目根目录，装上这个神器： npm install -D openapi-typescript-codegen 然后在 package.json 的 scripts 里加上这条命令： "gen-api": "openapi --input http://localhost:8000/openapi.json --output ./src/api/generated --client axios" 这里解释一下： --input 指向你后端给的“菜单”地址， --output 是代码生成的位置， --client axios 意思是生成的请求函数基于 axios（如果你的项目用 fetch 可以选 fetch）。 第三步：运行，见证奇迹。 执行 npm run gen-api 。