隆重推出 Forge：用于生成 SDK、CLI、文档等的开源生成流水线

今天，我们推出 Forge——一种生成 SDK、CLI、文档和库的全新方式。Forge 是一款开源的可插拔生成流水线，任何人都可以免费部署和运行。

Forge 尚处于早期阶段，但已经能够生成 cf CLI 所需的输出，并将在未来几个月内为 Cloudflare 的 API 文档、SDK 以及更多内容提供支持。

我们构建 Forge 是因为我们自己需要它，以便将 AI 智能体视为我们的客户。现在，我们将其开源，因为我们认为每个人都应该能够生成 AI 智能体所需的所有接口。过去，只有面向开发者的产品才需要 CLI、API SDK 和 MCP 服务器，以及与之配套的出色文档。如今，这些已成为每个产品的基本门槛。

我们的 API 超出了生成器的处理能力

Cloudflare 的 API 拥有超过 3,500 个操作，驱动这些 API 的数百个服务以多种语言编写，包括 Rust、Go、TypeScript 和 Python。当我们着手为整个 Cloudflare API（包括 SDK 和 API 文档）构建一个 CLI 时，我们需要一个能够应对这种规模的代码生成流水线。该流水线需要足够灵活，能够跨语言工作，并适应我们各个工程团队的运作方式。

我们需要一种方法来减少团队之间的协调开销。当 Cloudflare 产品团队进行 API 变更时，他们需要在合并变更并发布给客户之前，能够使用即将生成的 Cloudflare 全局 CLI、SDK 和文档站点的预览版本。我们需要一种方式确保他们不会无意中破坏生成流水线。我们还需要一个可以扩展的系统，用于生成不仅仅是 SDK 的内容——从 Cap'n Web 到 MCP，乃至更多。

我们试用过几款试图解决此问题的托管产品，并在生产中依赖了其中一些。但没有一款真正为我们解决了这个问题，部分甚至已经完全关闭。一个团队合并了一个无意中破坏生成流水线的变更，另一个团队在发布时才发现问题，我们浪费了太多时间在无法掌控的托管工具中逆流而上，协调团队与供应商之间的变更。

这就是我们开始构建 Forge 的起因。

Forge 旨在解决所有这些问题：它在 CI 中运行，在每个团队的 API 仓库上运行，就像我们的 AI 代码审查员和测试流水线一样。它对每次变更进行 lint 检查，然后生成 CLI、文档和 SDK 的预览版本，仅突出显示您的变更，您可以安装并测试。这与 Workers Previews 的理念相同：为每次变更提供完整的预览版本构建，但应用于大规模的 SDK 生成——即使 API 接口分布在数百个服务和仓库中也不例外。这就是 Forge 致力于实现的目标。

Forge 转换器可以生成任何内容，包括 Cap'n Web

Cloudflare 比大多数公司更有理由需要一个能够远超常规语言目标的生成器。Cap'n Web 是 Cloudflare 的 RPC 系统，它让 TypeScript 可以像调用本地方法一样调用远端 API。

// Authenticate, get the user's ID, fetch their profile, and fetch every friend's profile...
let authed = api.authenticate(apiToken);
let profile = api.getUserProfile(authed.getUserId());
let friends = authed.getFriendIds().map(id => api.getUserProfile(id));

// ...in a *single* request
let [me, myFriends] = await Promise.all([profile, friends]);

借助 Forge，可以获取一份 OpenAPI 规范并直接生成 Cap'n Web。这为从 Workers 到其他 API 的绑定生成打开了大门。毕竟，Workers 运行时中的绑定是作为暴露 RPC 方法的 Workers 来实现的。

这并非 Cap'n Web 独有的需求：您可能已经依赖的其他热门工具也有同样的需求。如果您使用 TanStack Query，理想情况下，您会希望能够直接从 API 本身生成适合您应用的 TanStack Query 绑定。始终保持最新，始终根据您的真实 API 进行验证。生成 Zod 或 Valibot 模式、MCP 服务器，或任何其他让 API 更易消费的内容，道理也是一样。

这之所以可行，是因为 Forge 代码生成器足够灵活。它们天生就是为了将信息从一个输出流向另一个输出而构建的。

Forge 转换器可以链式调用：从其他输出生成输出

我们将 Forge 设计成可插拔的，并支持多种输入和输出类型。Forge 提供 CLI、SDK 和文档生成器，但没有什么能阻止您添加一个生成特定库包甚至完整仪表板或应用程序的转换器。Forge 目前支持 OpenAPI 作为输入类型，但我们的设计允许未来支持 AsyncAPI、GraphQL、Cap'n Proto、Protobuf 或其他输入格式。

这不仅仅是兼容性问题：它让您可以链接目标，使用一个目标的输出来生成其他目标。这在其他生成器中很常见，例如 CLI 和 Terraform 目标从 Go SDK 生成。但缺少的——也是 Forge 所提供的——是一种让用户自己控制这个链式系统的方式。

我们自己也需要这个解决方案，因为我们的 cf CLI 是用 TypeScript 编写的，而其他 SDK 生成器通常不会将 TypeScript 作为 CLI 的链式来源。但我们自身的处境让我们认识到了更深层的问题：为什么 SDK 生成器工具要替您做这个决定？也许您是一个 Python 团队，希望 CLI 也用 Python 编写。

如果您在想“这有什么关系，Python 还是不是 Python？代码是自动生成的”——原因在于 CLI 是不同的。CLI 往往会引入一些只在本地有意义的行为，这些行为在 SDK 中并不合适。这些行为需要手动编写，因为它们本质上不是由任何 API 调用支撑的。例如，cf CLI 有 cf dev 和 cf build 这样的命令，它们是在其余生成输出之上额外添加的。这些命令需要调用其他包（如 Vite）中的 TypeScript API。

现在，我们再把文档加入其中。如果您纯粹从 OpenAPI 规范生成 CLI 和文档，您如何将那些手写命令重新融入文档，使它们能与其余内容一起得到记录？

我们找不到目前能做到这一点的现有工具，然而这正是我们为 cf 所需要的。所以我们将它内置到 Forge 中。

在不影响用户的情况下更改您的 API

Forge 也在为我们更好的 API 版本管理奠定基础。Cloudflare 的 v4 API 10 年来一直是我们 API 的唯一主要版本。在此期间，表面上我们似乎没有发布任何新的主要版本，但按照 SemVer 的定义，我们其实进行了不少值得新主要版本的变更。与此同时，API 中的多个操作带有内部的“v2”标签或“beta”标识，而这些标签早已超出了产品生命周期的那个阶段。

经历了这么多年的 v4 API，我们深知一个全新的大版本 v5 会让很多客户无法跟进。这就是为什么在 Forge 持续发布产物的同时，我们正在研究一种 API 版本管理方案，使我们能够发布新的主要 API 版本，而不破坏旧的客户端或 SDK。

关于我们的 SDK（包括 TypeScript、Rust、Python、Go、PHP 和 Terraform），我们很快会有更多消息分享。尤其是 Terraform。我们知道升级任何 Terraform 提供商都有其独特的严格性要求，我们将为 Terraform 的过渡倾注格外细致的心力。

关键工具应向所有人开放

我们相信，为 API 构建工具是互联网的核心组成部分，您应该能够在无需 SaaS 产品的情况下做到这一点。您应该拥有自己的 SDK、CLI 和文档。如果您自己生成这些，那么您应该能够随心所欲地使用它们，在任何地方，免费。

这就是为什么我们在宽松的 Apache 2.0 许可证下将 Forge 以开源方式发布。我们希望大家能加入我们的这段旅程，共同贡献。

或者不参与也可以？也许您想把一切都据为己有。没问题！您可以出于任何目的、进行自定义修改、免费、私下运行 Forge。

致谢：本项目也得益于 Dan Carter、Steven Chong、Krishna Paritala 和 Shelley Jones 的设计与实现工作。