深度解析 Cloudflare 开源的 Forge：一份 OpenAPI 规范同时生成 cf CLI、多语言 SDK 与 API 文档

Forge是 Cloudflare 开源的一套 schema-first 的 OpenAPI 代码生成与"接口面"（surface）工具框架：只要维护一份 OpenAPI 3.x 规范，它就能同时产出cf CLI、多语言 SDK（TypeScript、Go、Python 等）以及面向人类和 AI 的 API 文档。这套框架采用插件化架构，核心引擎位于 packages/forge/，文档引擎位于 packages/astro-fern/。

为什么需要 Forge？

API 生态中最常见的痛点是"多份产物各说各话"：CLI 的参数、SDK 的方法签名、文档里的示例，往往由三套人马分别维护，时间一长必然漂移。

Forge 的思路是单一事实源：

• OpenAPI 规范描述"这个 API 长什么样"；
• JSONPath 风格的Overlay负责在不污染上游规范的前提下，注入 CLI/SDK 专属的元数据（参数别名、确认提示、命令分组等）；
• 各个"transformer"（转换器）插件读取同一份解析后的模型，分别输出 CLI、SDK 和文档。

换句话说，改一处规范，所有产物同步更新。

项目结构与包职责

仓库是一个 pnpm monorepo，各包分工非常清晰（架构说明见 AGENTS.md）：

⚠️ 一个值得注意的架构约定：通用包（forge、astro-fern）不依赖任何 Cloudflare 专属内容，所有 Cloudflare 专属配置都放在cloudflare-*前缀的包里。这意味着你可以把 Forge 拿去为自己的 API 服务。

核心工作流：从规范到产物

1. 初始化：init()与 Overlay 解析

生成入口是异步工厂函数init()（见 init.ts）：

import { init } from '@cloudflare/forge'; const forge = await init(openapi, overlays);

它会依次完成：解析 OpenAPI 文档 → 按名称排序并逐个应用 Overlay → 构建类型化的命令/方法模型。Overlay 遵循 OpenAPI Overlay Specification v1.0.0，通过actions数组精确地"打补丁"——比如给某个操作注入x-forge-args（CLI 参数定义）或x-forge-require-confirmation（危险操作确认提示）。类型定义见 overlay-types.ts。

2. 插件化的 Transformer 模型

Forge类是所有生成器的宿主（核心实现见 forge.ts）。一个 transformer 就是一个简单的函数：

type TransformerFn = (forge: Forge) => Promise<void>;

transformer 内部通过forge.emit(path, content)缓冲文件，forge.transform(fn)执行后返回全部SourceFile，最后forge.finalize()把文件写到磁盘（并可选清理输出目录）。

同一个Forge实例可以反复用于不同 transformer——这正是"一份规范、多种产物"的机制保证。此外，Forge还内置了operationId索引、重复 ID 检测、$ref解析、按状态码匹配响应（精确码 →2XX/4XX区间 →default）等实用查询接口，详见 forge.ts。

三大产物详解

1️⃣ cf CLI：当前最优先的输出

README 明确写道，Forge 当前"激光聚焦"的第一个输出就是cf CLI。CLI 元数据通过x-forge-commands根字段声明命令树：命令名 → 描述 → 方法列表（每个方法绑定一个operationId+ SDK 方法名 + 可用性状态）。相关 schema 定义在 schema/schema.ts 与 overlay-types.ts。

命令树的目录与统计可以直接由引擎计算：methodMap()生成层级化的方法树，methodStats()统计方法分布（见 forge.ts）。

2️⃣ 多语言 SDK：基于 Fern 生成器

SDK 生成复用了 Fern 生态。共享的规范与生成器配置放在 cloudflare-fern-config/fern/generators.yml，一条脚本命令即可按语言生成：

tsx scripts/generate-sdk.ts # 默认 TypeScript tsx scripts/generate-sdk.ts python go rust # 任意语言组合

脚本 generate-sdk.ts 在本地与 CI 执行完全相同的流程：解析规范 → 调用 Fern 生成器 → 叠加自定义 runtime。TypeScript SDK 还额外生成sdk-map.json（operationId → SDK 调用点映射），保证文档示例与 SDK 实际调用点永不漂移，逻辑在 generate-fern.ts。

3️⃣ API 文档：人类页面 + AI 的llms.txt

文档侧由两个包协作：

• astro-fern（README）：负责加载 OpenAPI、构建 catalog、规划路由、输出操作产物（operation artifacts）。它还内置agent 文档能力——为每个操作自动注入 Markdown 页面和多级llms.txt索引（站点级、产品级、快照级、target 级），让 LLM Agent 也能高效检索 API 内容。
• docs-site（README）：Cloudflare 实际部署的 API 参考站，基于 Astro + Starlight 渲染，支持?lang=typescript选择执行目标、?version=切换历史版本快照。

数据流向非常直观（摘自 docs-site/README.md）：

OpenAPI source or version-bound snapshots + manifest ↓ route-neutral apiReference + runtime routing ↓ astro-fern server composition / | \ Starlight 页面 | agent Markdown 和 llms.txt | target metadata

而 fern-forge 则是桥梁：它校验x-forge-*/x-fern-*扩展字段、把 SDK 分组投影贡献给产品发现，并支持x-forge-aliases——让同一个物理操作以不同产品名出现在 SDK 与文档中。

快速上手

git clone https://gitcode.com/gh_mirrors/forge55/forge cd forge pnpm install

常用命令（见 AGENTS.md）：

pnpm check # 格式化 + lint（oxfmt + oxlint） pnpm typecheck # 全量严格类型检查 pnpm test # Node 原生测试运行器 pnpm --filter docs-site dev # 本地跑文档站

环境要求：Node.js ≥ 22、pnpm 10.27。

总结：值得关注的理由

• 一份规范，全端一致：CLI、SDK、文档共享同一个解析模型，从机制上消除漂移；
• Overlay 解耦：业务方元数据通过标准 Overlay 注入，上游 API 规范保持干净；
• 插件化 transformer：新增一种产物（比如 Terraform、Go CLI）只需写一个新 transformer；
• AI 原生：llms.txt与 Markdown 操作文档是内置能力，而非事后补丁。

项目目前仍处于 early-days 阶段（Apache-2.0 协议），Cloudflare 表示后续会陆续开放 TypeScript、Go、Python、Terraform 等更多 target。如果你的团队也在维护"规范 → 多产物"的流水线，这套设计模式值得直接借鉴。