【免费下载链接】forge项目地址https://gitcode.com/gh_mirrors/forge55/forge点击查看免费下载Forge是 Cloudflare 开源的一套 schema-first 的 OpenAPI 代码生成与接口面surface工具框架只要维护一份 OpenAPI 3.x 规范它就能同时产出cf CLI、多语言 SDKTypeScript、Go、Python 等以及面向人类和 AI 的 API 文档。这套框架采用插件化架构核心引擎位于 packages/forge/文档引擎位于 packages/astro-fern/。为什么需要 ForgeAPI 生态中最常见的痛点是多份产物各说各话CLI 的参数、SDK 的方法签名、文档里的示例往往由三套人马分别维护时间一长必然漂移。Forge 的思路是单一事实源OpenAPI 规范描述这个 API 长什么样JSONPath 风格的Overlay负责在不污染上游规范的前提下注入 CLI/SDK 专属的元数据参数别名、确认提示、命令分组等各个transformer转换器插件读取同一份解析后的模型分别输出 CLI、SDK 和文档。换句话说改一处规范所有产物同步更新。项目结构与包职责仓库是一个 pnpm monorepo各包分工非常清晰架构说明见 AGENTS.md包职责packages/forge/核心引擎OpenAPI 3.x 解析器、类型化 Schema 模型、JSONPath Overlay、插件生命周期packages/astro-fern/通用的 Astro 文档引擎加载 OpenAPI、构建目录、规划路由、渲染 Markdownpackages/docs-site/可直接部署的 API 文档站Astro Starlight astro-fernpackages/fern-forge/把 Forge 的x-forge-*元数据校验并适配进 astro-fern 扩展 APIpackages/cloudflare-fern-config/Fern 生成器配置generators.yml与多语言 SDK 生成脚本packages/cloudflare-forge-sdk-ts/TypeScript SDK 封装与sdk-map生成器packages/cloudflare-forge-sdk-go/ 等Go、Python、Java、PHP、C#、Ruby、Rust、Swift 的语言工作区封装⚠️ 一个值得注意的架构约定通用包forge、astro-fern不依赖任何 Cloudflare 专属内容所有 Cloudflare 专属配置都放在cloudflare-*前缀的包里。这意味着你可以把 Forge 拿去为自己的 API 服务。核心工作流从规范到产物1. 初始化init()与 Overlay 解析生成入口是异步工厂函数init()见 init.tsimport { init } from cloudflare/forge; const forge await init(openapi, overlays);它会依次完成解析 OpenAPI 文档 → 按名称排序并逐个应用 Overlay → 构建类型化的命令/方法模型。Overlay 遵循 OpenAPI Overlay Specification v1.0.0通过actions数组精确地打补丁——比如给某个操作注入x-forge-argsCLI 参数定义或x-forge-require-confirmation危险操作确认提示。类型定义见 overlay-types.ts。2. 插件化的 Transformer 模型Forge类是所有生成器的宿主核心实现见 forge.ts。一个 transformer 就是一个简单的函数type TransformerFn (forge: Forge) Promisevoid;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.jsonoperationId → SDK 调用点映射保证文档示例与 SDK 实际调用点永不漂移逻辑在 generate-fern.ts。3️⃣ API 文档人类页面 AI 的llms.txt文档侧由两个包协作astro-fernREADME负责加载 OpenAPI、构建 catalog、规划路由、输出操作产物operation artifacts。它还内置agent 文档能力——为每个操作自动注入 Markdown 页面和多级llms.txt索引站点级、产品级、快照级、target 级让 LLM Agent 也能高效检索 API 内容。docs-siteREADMECloudflare 实际部署的 API 参考站基于 Astro Starlight 渲染支持?langtypescript选择执行目标、?version切换历史版本快照。数据流向非常直观摘自 docs-site/README.mdOpenAPI 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.mdpnpm check # 格式化 lintoxfmt 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只需写一个新 transformerAI 原生llms.txt与 Markdown 操作文档是内置能力而非事后补丁。项目目前仍处于 early-days 阶段Apache-2.0 协议Cloudflare 表示后续会陆续开放 TypeScript、Go、Python、Terraform 等更多 target。如果你的团队也在维护规范 → 多产物的流水线这套设计模式值得直接借鉴。赞分享【免费下载链接】forge项目地址https://gitcode.com/gh_mirrors/forge55/forge点击查看免费下载相关推荐Hey API 开源生态深度解析从 OpenAPI 规范生成生产级 SDK、校验器与 Mock 的代码生成器Hey API 开源生态深度解析从 OpenAPI 规范生成生产级 SDK、校验器与 Mock 的代码生成器 本篇指南围绕 Hey API 开源仓库当前仓库开发工具代码生成API设计后端Cangjie 语言 API 面规范与 LLM 文档生成实战CangjieMagic doc_generator 示例深度解析Cangjie 语言 API 面规范与 LLM 文档生成实战CangjieMagic doc_generator 示例深度解析 在 CangjieMagic人工智能大模型AI AgentRAG工具调用MCP 服务MCP Clients多智能体Hyperf API文档生成Swagger与OpenAPI规范实践Hyperf API文档生成Swagger与OpenAPI规范实践 你是否还在为API文档维护耗费大量精力是否遇到过接口变更与文档不同步导致的联调灾难本文后端微服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考