构建自动化SDK流水线的经验教训
内容提要
Cloudflare现在提供Typescript、Go和Python的软件开发工具包（SDK）。这些SDK使用OpenAPI生成，旨在在不同的编程语言中提供一致且高质量的体验。使用OpenAPI可以实现快速反馈循环、清晰的约定和对新功能的统一支持。Cloudflare选择使用Stainless生成引擎构建SDK，并发现它是一个可靠的解决方案。过渡到OpenAPI和使用SDK极大地提高了Cloudflare的开发过程的效率和质量。
延伸解读
从手动维护到自动生成：效率提升的关键
Cloudflare 的 SDK 曾依赖人工维护，导致更新频率和质量不均衡，甚至需要协调多个拉取请求。过渡到 OpenAPI 生成后，大部分更改只需一个拉取请求，且能自动生成 TypeScript、Go 和 Python 三个语言的 SDK。这种自动化不仅减少了人为错误，还让团队能专注于编写高质量的 API 模式，而非维护生成逻辑。
一致性优先：设计原则与工具支持
Cloudflare 强调 SDK 应隐藏底层生成语言，提供符合语言习惯的接口，并确保不同语言中命名空间和方法的一致性。为此，他们使用 Lint 规则（如 Redocly 插件）在 CI 中强制 API 设计规范，例如要求 API Token 认证方案优先，以及描述格式统一。这些措施降低了端点质量差异，提升了开发者体验。
大规模重构与迁移：Codemods 和 Grit 的应用
面对约 1300 个公开端点，Cloudflare 使用 Codemods（如 comby）进行大规模代码重构，统一路径参数和命名。对于客户 SDK 迁移，他们采用 Grit 工具，提供简单的 CLI 命令（如 grit apply cloudflare_go_v2），使迁移过程更易用。这些工具帮助团队和用户高效适应 API 变更。
经验教训：谨慎使用 $ref 与设计先行
Cloudflare 建议避免过度使用 $ref，因为它可能导致模式难以更改和隐藏错误，例如 created_at 错误引用 updated_at 的描述。他们推荐仅在 oneOf、allOf 等场景使用 $ref，并遵循 YAGNI 原则。此外，在设计 SDK 前应编写语言设计文档，优先考虑用户体验而非技术挑战，从而提前识别语言差异问题。
Q&A
Cloudflare提供哪些编程语言的软件开发工具包（SDK）？
Cloudflare提供Typescript、Go和Python的软件开发工具包（SDK）。
使用OpenAPI生成SDK有什么好处？
使用OpenAPI生成SDK可以实现快速反馈循环、清晰的约定和对新功能的统一支持，减少手动维护的错误和复杂性。
Cloudflare是如何提高SDK的开发效率和质量的？
Cloudflare通过过渡到OpenAPI和使用Stainless生成引擎，减少了手动维护的复杂性，提高了开发效率和质量。
在设计SDK时，Cloudflare强调了哪些指导原则？
Cloudflare强调的指导原则包括SDK不应受底层语言影响，确保一致性和用户体验优先。
Cloudflare如何确保API设计的一致性和质量？
Cloudflare使用Lint规则和CI机制来确保API设计的一致性和质量，及时发现并修复问题。
Cloudflare未来有什么计划与SDK相关的改进？
Cloudflare计划在2024年推出更多SDK和改进，并欢迎用户反馈以确定下一个支持的语言。
