跳到主要内容

7.4 OpenAPI 客户端生成

当 API 增多后，手写前端类型很容易和后端 DTO 脱节。OpenAPI 客户端生成可以把后端契约转换成 TypeScript 类型和请求函数，减少重复劳动。

学习目标​

  • 理解 OpenAPI 在前后端协作中的位置。
  • 能判断哪些接口适合生成客户端。
  • 能设计稳定 DTO，减少破坏性变更。
  • 能把生成代码放到合适目录并避免手改。

应用场景​

  • React 前端需要大量调用 ASP.NET Core API。
  • 多个前端共用一套后端接口。
  • API 字段变化后希望 TypeScript 编译能立刻报错。
  • 团队希望减少手写 API Client 的重复代码。

流程​

生成目录建议​

frontend/
  src/
    api/
      generated/
        client.ts
        schemas.ts
      todoApi.ts

generated 目录只放生成文件，不手动修改。业务层可以在 todoApi.ts 中封装更友好的函数。

契约稳定策略​

变化兼容性建议
增加可选字段通常兼容推荐
删除字段破坏性新版本接口或过渡期
改字段类型破坏性避免直接修改
改错误格式破坏性统一错误契约后保持稳定

重点难点​

  • 生成代码不是业务抽象，页面不一定要直接依赖生成函数。
  • 后端 DTO 命名和字段可空性会直接影响前端类型体验。
  • 生成流程要进入 CI，避免本地忘记更新。
  • 接口版本管理比临时改字段更重要。

常见误区​

误区推荐做法
生成代码后手动修改只在业务封装层修改
API 字段随意重命名按兼容性策略演进契约
只生成类型不验证错误响应成功和失败契约都要覆盖

练习​

  • 导出当前 API 的 OpenAPI JSON。
  • 为 React 项目生成 TypeScript 类型。
  • 改一个 DTO 字段名，观察前端编译错误。

延伸阅读​

  • OpenAPI。
  • NSwag / Kiota / openapi-typescript。
  • API 版本管理。