OpenAPI SDK 生成器

要解决什么问题

团队一旦同时维护多语言客户端，手写 SDK 的成本就会失控：接口字段变更后，各端需要逐一同步修改，类型定义与服务端契约逐渐漂移，认证拦截器和重试逻辑在不同语言里重复实现且行为不一致。这个技能的目标是把这类重复劳动交给代码生成：只要持有一份可信的 OpenAPI 3.x 规范，就能批量产出类型安全的客户端与服务端桩代码。

技能如何工作

核心流程围绕 openapi-generator-cli 展开：

• 解析规范：读取 OpenAPI 3.x 描述文件（YAML 或 JSON），提取路径、参数、请求体与响应模型。
• 生成客户端：默认聚焦 TypeScript、Python、Go 三种目标语言，产出带类型标注的客户端代码。
• 内置横切能力：生成结果包含认证拦截器与重试逻辑，省去在各语言里重复造轮子。
• 服务端桩代码：除客户端外，上游生成器还覆盖大量服务端框架的 stub（如 Go 的 net/http、Gin、Echo，C# 的 ASP.NET Core 等），便于快速搭建 mock 服务。
• 语言覆盖面广：客户端侧还支持 C#、C++、Java 等数十种语言，适配团队混合技术栈的需求。

适用边界与注意点

• 前提是规范本身准确。生成器无法纠正上游文档中的错误，建议配合 CI 对规范做校验。
• 运行依赖 Java 运行时；如果环境不方便安装本地工具链，可以使用上游提供的 Docker 镜像隔离执行。
• 生成代码是起点而非终点，业务级定制（特殊错误码处理、分页约定等）仍需在生成后追加手写层，建议通过生成后钩子或 overlay 文件管理差异。
• 生成器的模板与支持矩阵跟随上游版本演进，升级前建议先用一份代表性规范做回归验证。