从 OpenAPI 生成 SDK 工作流

概述

手工维护多语言 SDK 会很快与契约脱节并堆积实现差异。由契约生成、与 API 版本对齐、先对模拟再对真实服务测试，并按语言发布且变更日志源自 API 变化，可让消费方拿到一致且经测试的客户端。

关键步骤

1. 由契约生成客户端而非手工编写。
2. SDK 版本与 API 版本对齐。
3. 先对模拟再对真实服务测试生成的客户端。
4. 按语言发布并同步变更日志。

验证

• 生成的 SDK 通过契约与集成测试。
• SDK 版本可映射到 API 版本。
• 契约更新后 SDK 重新生成。
• 发布有标签与契约修订记录。

决策点

为一致性宜生成而非手工编写，仅在易用性需要时手写薄封装；多语言维护者不同时可用各语言独立仓库。

适用范围

本条目围绕「从 OpenAPI 生成 SDK 工作流」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。

npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g typescript-fetch -o sdk/ts
# then run integration tests against staging