openapi-typesafe —— 类型安全的 OpenAPI 客户端,已为 TypeScript 7 做好准备

先生成类型,再用类型化的客户端调用你的 API:

为什么要做它

openapi-typescript 和 openapi-fetch 是很多 TypeScript 团队对接 API 的方式:把一个 OpenAPI schema 交给它们,就能得到每个路径、参数和响应的类型。2026 年 9 月,它们的作者 停止了维护。

与此同时,TypeScript 7 来了。它是编译器的原生移植版,它的 typescript 包没有 JavaScript API:没有 ts.factory,也没有 printer。openapi-typescript 的每个类型都是用 ts.factory 构建的,所以在 TypeScript 7 的项目里,它要么装不上,要么一加载就崩溃。

于是,成千上万个项目手里有了一个既没人维护、又马上要坏掉的依赖。

我做了什么

我带着完整的上游历史 fork 了它,并定下一条规则:迁移只能是改个包名,别的什么都不用动。 同样的 CLI 参数、同样的 Node API、同样的生成结果、同样的客户端。

• 一个不依赖编译器 API 的生成器。 类型被构建成我们自己的一棵小树,再由我们自己的 printer 打印出来。它完全不需要 typescript 包,所以能和 TypeScript 5、6 或 7 一起运行。
• 支持 OpenAPI 3.2,原版会直接拒绝它。
• 一个迁移工具 (openapi-typesafe-migrate),帮你把项目迁过来:imports、脚本和包配置。
• TanStack Query 绑定 和共享的类型辅助工具,同样可以直接替换。

我怎么知道它是兼容的

"可直接替换"是一个承诺,所以必须测量,而不是嘴上说说。一份公开的 兼容性报告 把我们的输出和 openapi-typescript 7.13 在 1,820 份真实 OpenAPI 文档 上做对比:整个 APIs.guru 目录,再加上 GitHub、Stripe、OpenAI、Cloudflare 和 Kubernetes 这样的大家伙。每个 schema 用 28 组选项运行,所以一共是 50,960 个用例。

每个用例分三步检查:先看字节是否相同,再看类型是否相同(严格的同一性检查),最后看能不能编译。最近一次运行:99.87% 逐字节相同,100% 类型相同,0 个意外差异。CI 每晚跑一遍完整语料,每次发布都会附上它的报告链接。

安全的发布

代码生成器在你的机器上运行,并往你的项目里写代码,所以它的供应链很重要:

• 依赖尽量少;
• npm provenance,没有长期有效的发布令牌;
• 威胁模型、带响应时限的安全策略,以及私密的漏洞报告渠道;
• OpenSSF Scorecard 和 OpenSSF Best Practices 徽章。

为编码代理而做

仓库里附带一个 agent skill,教 Claude Code(或任何能读取 skills 的代理)如何配置客户端、发起类型化调用、处理错误,以及从 openapi-typescript 迁移过来。另有一套独立的 eval 用 34 个编码任务来衡量这个 skill。文档站提供 llms.txt、llms-full.txt,以及每个页面的 Markdown 副本。

我用 agentic engineering 的方式构建了它:编码代理写代码,而我负责设计、兼容性规则,以及证明这条规则成立。

状态

候选发布版:npm 上的 1.0.0-rc.4。在 1.0.0 之前,名称和输出仍可能变化;之后遵循语义化版本。MIT 许可证。