Cloudflare Forge：把 SDK / CLI / 文档生成做成开源管道
阅读时间: 大约 9 分钟
Cloudflare Forge：把 SDK / CLI / 文档生成做成开源管道
2026 年 9 月 28 日（Cloudflare Birthday Week），Dimitri Mitropoulos、Matt “TK” Taylor 与 Samuel Macleod 在官方博客发布并开源了 Forge：一条可插拔、任何人都能免费部署运行的代码生成管道，用来从 API 规范自动产出 SDK、CLI、文档、库乃至 MCP 服务器。官方称它”已经在为 cf CLI 生成所需产物”，未来数月还将接管 Cloudflare 的 API 文档与各语言 SDK。许可证为宽松的 Apache 2.0。
一、为什么 Cloudflare 要重写自己的生成器
Cloudflare 的 API 规模是这件事的起点：官方称其 API 有超过 3500 个操作，背后由数百个服务驱动，这些服务分别用 Rust、Go、TypeScript、Python 写成。当他们要为整个 Cloudflare API 构建统一的 CLI、SDK 和文档站时，就需要一条能跨语言、跨团队工作方式的生成管道。
他们过去尝试并依赖过若干托管（SaaS）代码生成产品，结论是：没有一个真正解决这个问题，其中一些还直接关停了。更痛的是协作模型——某个产品团队合并了一个改动，无意中破坏了生成管道，而另一个团队要到发版时才发现，于是只能回滚上游的多个 PR。
Forge 的思路是把生成管道放进每个团队自己的 CI 里，像代码审查和测试流水线一样：每次改动都先 lint，再生成一个只含本次改动的可安装预览版（CLI、文档、SDK）。这与 Workers Previews”每次改动都给一个完整预览”的理念一致，只是把它搬到了横跨数百仓库的 SDK 生成上。
二、是什么：一条可链式组合 Transformer 的管道
Forge 不是”从 OpenAPI 到某语言 SDK”的单点转换器，而是一组可以串接的 Transformer（转换器）。官方给出的主干链路是：OpenAPI 规范 → 生成 TypeScript SDK → 再从 TypeScript SDK 生成 cf CLI 与 Cap’n Web（Cloudflare 的 RPC 系统，让 TS 像调本地方法一样调远程 API）→ 最后连同各语言产物一起汇总成文档。
这个”链式”是 Forge 与多数生成器的关键差异。传统工具通常固定地从某一个中间产物（如 Go SDK）派生 CLI 和 Terraform，用户没有控制权。Forge 把决定权交回用户：Cloudflare 自己的 cf CLI 是 TypeScript 写的，而别的生成器一般不会从 TypeScript SDK 派生 CLI；如果你是 Python 团队，也完全可以让 CLI 用 Python 生成。
支持这种链式的另一个现实原因是：CLI 与 SDK 不同。CLI 常常带一些纯本地、不对应任何 API 调用的手写命令，例如 cf CLI 的 cf dev、cf build，它们要调用 Vite 等其它包的 TypeScript API。如果 CLI 和文档都纯由 OpenAPI 生成，这些手写命令就无法进入文档。Forge 的做法是让手写命令与生成代码混排，并把它们一并反馈进文档产物。
三、输入与输出：今天支持什么，规划支持什么
| 维度 | 当前（官方口径） | 规划中 |
|---|---|---|
| 输入规范 | OpenAPI | AsyncAPI、GraphQL、Cap’n Proto、Protobuf、Arazzo |
| 输出语言 SDK | TypeScript（已用于 cf CLI） | Rust、Go、Python、PHP、Terraform |
| 衍生产物 | cf CLI、Cap’n Web、文档 | MCP 服务器、Changelog、TanStack Query / Zod / Valibot 绑定 |
| 运行位置 | 跑在各团队 CI，每 PR 生成预览 | — |
官方特别强调 Terraform：他们知道升级任何 Terraform provider 都极其严谨，会在迁移上格外小心。此外，Forge 还在为 Cloudflare 的 API 版本化铺路——v4 API 已经用了 10 年，期间按 SemVer 标准其实已经攒下不少”够格发大版本”的改动，但直接切 v5 会抛弃大量老客户；Forge 在沿途产出构件的能力，正是为”发新大版本而不破坏老 SDK”服务的。
四、评测方法与口径偏差
需要泼几盆冷水：
- 项目尚处早期。官方自述”early in its life”，今天的输入只支持 OpenAPI，AsyncAPI/GraphQL/Protobuf 等都还是”设计上支持、尚未落地”；多语言 SDK 与 Terraform 也还在路线图上。换句话说，现在能直接拿来用的成熟度有限，更多是这套架构思路。
- 没有公开的生成质量基准。Forge 是工程管道而非算法模型，官方没有、也不太可能给出”生成正确率”这类数字；它宣称的收益（失败提前到 PR 阶段、免去跨团队与供应商协调）来自 Cloudflare 自身规模的痛点，小团队未必有感。
- 对比对象是”商业 SaaS 关停”的叙事，而非逐项 benchmark。文中对 Stainless、Speakeasy 这类托管服务的批评是”解决不了我们的规模、有的关停了”，并没有给出生成代码质量的横向数据。这个结论对 3500 操作级别的公司成立，不等于小团队迁过去一定更省事。
五、优势与局限
优势：
- 去中心化、跑在 CI：每个 API 仓库自己 lint + 预览，失败在 PR 合并前就暴露，而不是发版时才发现；
- 可链式、用户可控：从哪个中间产物派生 CLI / MCP / RPC 由你定，手写命令能与生成代码共存并进入文档；
- 彻底开源、可私有运行：Apache 2.0，你可以本地改、私下跑，不依赖任何 SaaS，也不必交出自己的 API 规范。
局限：
- 生态早期：输入格式与目标语言覆盖不全，Terraform 等关键产物尚未就绪；
- 价值与规模强相关：它解决的是”数百仓库、3500 操作”的协调问题，单体小 API 用它可能比直接手写 SDK 更重；
- 迁移成本被轻描淡写：从现有托管生成器迁到自建 CI 管道，lint 规则、预览分发、跨仓库聚合都需要自己搭。
六、谁该关注
- 维护多语言 SDK / CLI 的平台型团队，尤其是 API 分散在大量仓库里、深受”上游一个改动弄坏下游生成”之苦的人；
- 想把 API 规范同时喂给 MCP 服务器、RPC binding、前端数据请求库的团队——Forge 的链式 Transformer 正好覆盖这类”一份规范、多个消费面”的需求；
- 对供应商锁定敏感、不愿把 API 规范交给第三方 SaaS 的组织。
如果你只是一个十来人的小服务、SDK 一年更新不了几次，那这套管道暂时 overkill；但它代表的”把开发者产物生成基础设施开源、免费化”方向，确实在挤压 Stainless 这一类商业 SDK 生成服务的空间。