Stainless SDK 生成器关停迁移指南：如何用 Scalar 读取 `stainless.yml` 复现你的 API 公开表面

Stainless 于 2026 年 5 月 18 日宣布加入 Anthropic 并关停全部托管产品（含 SDK 生成器），大量团队面临着"用户已经基于现有 SDK 写了代码，如何迁移而不破坏他们"的难题。本文以仓库内 The Stainless SDK generator wind-down 为核心，完整梳理关停公告的实际影响、全行业可选方案对比、stainless.yml 到 Scalar 配置的逐键映射，以及一条可验证、可执行的迁移路径。读完你将掌握：如何判断一个生成器能否复现你现有的公开 API 表面、如何完成 stainless.yml 的导入与 api.md 差异比对，以及迁移前后必须做好的工程准备。

事件背景：Stainless 的公告到底说了什么

Stainless 在 2026 年 5 月 18 日发布公告，宣布其正在加入 Anthropic，并同步关停全部托管产品。公告原文为：

"As we focus on Claude Platform capabilities and connecting agents to APIs, we'll be winding down all hosted Stainless products, including our SDK generator. Starting today, new signups, projects, and SDKs will not be available."

这句话里有三点容易被混为一谈，需要拆开理解：

1. 关停的是"全部托管产品"，不仅仅是 SDK 生成器，其 Docs Platform 同样在列。
2. 新注册、新项目、新 SDK 在公告当天即关闭，这不是一个远期预告的弃用计划。
3. 已生成的代码归你所有。Stainless 明确表示："As always, you own the SDKs you've generated to date, and have full rights to modify and extend them however you wish."

Stainless 将存量客户引导至 app.stainless.com/transition 页面；仓库文档明确指出，该页面在账号之外无法查看，因此如果你是存量客户，应先阅读该页再做决策。

Stainless 并未公布存量项目的终止日期。 公告只覆盖了新注册、新项目与新 SDK，没有说明既有项目的构建何时——乃至是否——停止。仓库文档拒绝替对方猜测，并给出了务实建议：与其把"没有公布日期"当作安心剂，不如按自己的节奏推进迁移。该分析的研究日期为 2026 年 8 月 16 日，若 Stainless 后续公布了时间线，文中结论即可能过时（详见文末维护说明）。

现状盘点：什么继续工作，什么停止

"今天什么都不会坏"——这是真的，也正是这件事容易被无限期拖延的原因。

继续有效的内容：

• 你已发布的所有软件包，用户依然能按现状安装；
• 位于你组织名下、发布在你自己注册表上的 SDK 仓库；
• 其中每一行生成代码与手写代码，你拥有全部权利。

停止生效的内容：

• 再生成（Regeneration）。下一次你新增端点、调整响应结构或弃用字段时，不会再有任何自动更新；
• 新增语言目标。未生成过的语言将无法再补；
• Docs Platform（如果你用过）。Stainless 将这类仓库存放在 stainless-sdks GitHub 组织而非你的组织下，其官方托管指引要求你将 Astro 项目 fork 出来，自行接管仓库、CI、部署与域名，此后"你的组织对仓库、CI 配置、部署目标、域名配置及其他运维事项负全责"。

因此真正的截止日期不是 Stainless 的，而是你的下一次 API 变更。 在那之前，"什么都不做"的代价为零；在那之后，你的 SDK 与你的 API 开始脱节，且差距随每次发版扩大。

评估方案的正确姿势：问题不在 OpenAPI，而在 stainless.yml

一个显而易见的误读是："我有 OpenAPI 文档，每个生成器都能读 OpenAPI，所以我随便选一个就行。"这是最昂贵的错误认知。

你的 OpenAPI 文档从来不是离开 Stainless 的难点——它归你所有、可移植、描述了你的 API。但它不描述你的 SDK：哪些操作变成了哪些命名空间、每个方法叫什么、每个列表端点用哪种分页方案、客户端类叫什么、每种语言下包名是什么。这些决策全部存放在 stainless.yml 中，而它们没有任何一项可以在 OpenAPI 中表达。

只用规范重新生成，任何工具都会产出一个公开表面完全不同的 SDK：新的命名空间、新的方法名。这对所有已经基于你的包写了代码的用户都是一次破坏性变更，而代价由你的用户承担。

所以，评估下列每个选项时，要问的问题不是"它生成的代码好不好"——大多数都不差——而是：它能否复现我的用户已经在调用的公开表面？

可选方案逐一评估

仓库文档对每个方案都给出了"它在哪里比 Scalar 强"与"它的真实代价"两个维度，以下完整继承。

OpenAPI Generator

默认答案，对很多团队来说也是正确答案。OpenAPI Generator 采用 Apache-2.0 许可证、社区维护、提供覆盖极广的 80 余个客户端生成器，涵盖商业产品永远不会触及的语言（Ada、Elm、Erlang、OCaml、R、Xojo 等）。

它打败包括 Scalar 在内的所有商业选项的地方： 免费、无厂商绑定、没有任何公司能把它关停。如果你在经历这三个月后对"依赖一个托管生成器的存续"心有余悸，这是完全合理的结论，而这条路正通向这里。

诚实的代价： 输出由 Mustache 模板生成，很少能达到 Stainless SDK 那样的地道程度。没有 stainless.yml 的对应物，你的资源树、方法名与分页行为需要自己通过每生成器配置与模板重新表达。大多数走这条路的团队最终会拥有相当数量的模板和后处理代码——这是持续的维护承诺，而不是一次性迁移。

Speakeasy

最接近"托管、开箱即用"体验的直接替代品。Speakeasy 在其 README 中列出的语言包括 TypeScript、Python、Go、Java、C#、PHP、Ruby、Unity（"10 种语言且还在增加"），此外还覆盖 Terraform provider、CLI、MCP server 与契约测试。

Speakeasy 打败 Scalar 的地方：Terraform provider 生成。 Stainless 曾有 terraform 目标，而 Scalar 目前没有对应物。如果你原本就在从 API 描述生成 Terraform provider，Speakeasy 是直接答案。他们也生成 MCP server 与契约测试。

值得知道的细节： 免费层覆盖"1 个 SDK、最多 50 个 API 方法"，付费层提供 14 天试用。其定价页当前主打 MCP 与 AI 产品而非公开的 SDK 价目表，所以拿数字可能要找销售谈。Speakeasy 通过自己的 gen.yaml 与 workflow 文件配置，没有 stainless.yml 导入能力，因此保留现有公开表面是必须自行评估的手工工作。更完整的对比见仓库内的 Scalar vs Speakeasy。

Fern

Fern 于 2026 年 1 月被 Postman 收购，官方称产品与品牌继续独立运营，并已发布面向 Stainless 客户的迁移邀约。

Fern 打败 Scalar 的地方：协议广度与生成器开放性。 Fern 接受 AsyncAPI、OpenRPC、gRPC/Protobuf 作为 SDK 输入，这些 Scalar 目前都不支持；fern-api/fern 采用 Apache-2.0 且每种语言的生成器代码全部公开，你可以阅读产出 SDK 的代码本身，而 Scalar 的生成器是闭源的。如果这两点之一是你的硬性要求，Fern 是更好的工具。

值得知道的细节： Fern 的迁移材料更多是"帮助迁移的承诺"而非"可验证的机制"——截至撰写时它并未描述如何读取 stainless.yml 或复现你的既有方法名。其免费 SDK 层上限为 50 个端点，且相当一部分 SDK 特性为 Enterprise 专属、按 SDK 年付且无公开费率。详细分析见 Scalar vs Fern。

APIMatic

该类别中运营时间最长的商业生成器，也是定价最清晰的一个。支持七种语言，并公布了价目表：Lite 档 $10/月（一种语言、每个 API 20 个端点），Basic 档每语言 $300/月，更高需求定制报价。

APIMatic 打败 Scalar 的地方：经验时长与规范处理能力。 它自 2014 年起就在做这件事，其格式转换工具 API Transformer 处理的输入方言与遗留 Swagger 2.0 文档范围比多数现代生成器更广。如果你的 API 描述很旧、靠手工维护、或格式别人都读不了，这一点就很重要。

值得知道的细节： 按语言定价在多语言场景下会迅速变贵，低档位的端点上限也偏低，且没有 stainless.yml 迁移路径。

liblab

liblab 生成 TypeScript、Python、Java、.NET、Go、PHP 与 Terraform，通过 liblab.config.json 配置。

liblab 打败 Scalar 的地方：hooks 模型。 liblab 允许你在请求与响应生命周期的定义点注入代码，且这种注入能在再生成时干净地保留下来——如果你的 API 需要 OpenAPI 无法表达、但又存在于客户端侧的行为，这非常合适。它同样覆盖 Terraform，而 Scalar 不覆盖。

值得知道的细节： 与其他方案一样，没有 stainless.yml 导入，SDK 定价也未以价目表形式公开。

stainful

即使它不是商业产品也值得了解。stainlu/stainful 是一个 MIT 许可的开源生成器，直接读取你现有的 stainless.yml 并在本地运行，不涉及任何 SaaS。

它打败包括 Scalar 在内的所有选项的地方： 免费、MIT、运行在你的机器上、背后没有任何会被关停的公司。

诚实的局限： 截至 v0.4.0 它只生成 Python，而且是一个年轻项目——个位数规模的 star、单一维护者、且有公开的差距清单。它不是多语言 SDK 资产的一对一替代品。但如果你只用 Python，或想要一个能消费现有配置的本地逃生通道，它值得在签约任何方案之前看一眼。

oagen

WorkOS 发布了 oagen，并附带了一份行业格局调研。它是一个将 OpenAPI 解析为已解析的中间表示（IR）的框架，而不是开箱即用的生成器——emitter 由你自己编写。适合已经决定完全自持生成管线、且不想从 Mustache 模板起步的团队。

Scalar

Scalar 生成 TypeScript、Python、CLI、Go、Rust、Java、Kotlin、Swift、Ruby、PHP、C#、C++ 与 Dart 共 13 种目标。每个套餐包含一个目标，额外目标从每月 $150 起（价格公开），SDK 以你的包名存放在你的仓库中——Scalar 以 Pull Request 的方式合入，绝不代你打 tag。Scalar 还提供基于同一份 OpenAPI 文档构建的 MCP server：按端点选择工具、存储的认证信息、以及面向团队外部人员的 OAuth。这类服务由 Scalar 托管，与 Speakeasy"生成代码由你部署"是相反取舍。

这次情境下关注 Scalar 的具体理由：Scalar 将 stainless.yml 作为输入读取。 这不是泛泛的"我们更强"声明，而是一个恰好在此刻极其重要的结构性事实，也是下一节的主题。

Scalar 落后之处（如实说明）： 没有 Terraform 或 SQL 目标、不支持 gRPC/AsyncAPI/OpenRPC 输入、生成器闭源。在全部目标中，TypeScript、Python、Go 与 CLI 为正式可用（generally available），其余标记为 experimental。Terraform 与 SQL 在路线图上，但没有发布日期——若你今天就依赖 terraform 目标，应直接去看 Speakeasy 的资料，而不是等 Scalar。

stainless.yml 兼容性故事：逐键映射

"无缝迁移"不是任何人应该不假思索接受的承诺，需要一张逐键对照表来验证。两种配置描述的是同一类事物——资源树、目标、分页方案、客户端设置——因此映射大体上是机械性的；差异真实存在但可以一一列名。对照 Stainless 的 config schema 与 Scalar 的 SDK 配置参考：

stainless.yml	Scalar	说明
resources（methods、models、subresources）	resources（methods、models、subresources）	直接对应。这是让你的用户调用点保持可用的关键部分。
targets	targets	共享语言直接对应，缺口见下文。
environments	environments + environmentOrder	Stainless 默认首条为默认环境；Scalar 将顺序显式化。
client_settings	clientSettings	构造器选项、认证值、默认请求头、环境变量名、超时、重试。Scalar 中键为 camelCase。
pagination	pagination	Scalar 的类型为 cursor、cursorId、cursorUrl、offset、pageNumber。
query_settings	querySettings	数组格式 comma、repeat、indices、brackets；嵌套格式 brackets 或 dots。
multipart_settings	multipartSettings	直接对应。
security / security_schemes	openapi.security / openapi.securitySchemes	同一思想，不同嵌套层级。
streaming	streaming	直接对应。
settings	settings	两者都存在，但内容不同：Stainless 用于许可证，Scalar 用于文件头与响应解包。
organization	name	Scalar 取产品名；Stainless 其余组织元数据没有直接落点。

具体不迁移的部分：

• targets: terraform 与 targets: sql 目前没有 Scalar 对应物。 若你生成过其中之一，Scalar 无法替代。两者都在路线图上但无发布日期，请按"它们不会来"进行迁移。Speakeasy 与 liblab 现在都能生成 Terraform provider。
• openapi.transforms 没有 Scalar 对应物。 Scalar 的 openapi 键用于 SDK 专属覆盖（代码示例语言、安全方案覆盖），而不是重写输入文档。如果你用过 transforms，请以变换后的输出作为输入，让两个生成器看到同一份 API。这是迁移 diff 出错最常见的原因——因为仓库里的文档并不是 Stainless 实际生成所用的文档。
• edition。 Stainless 会钉住一个配置 schema 版本；Scalar 没有这个概念，无需迁移。
• readme。 Stainless 的 README 示例选择没有直接对应物。
• 命名约定。 Stainless 用 snake_case 键，Scalar 用 camelCase。纯属外观差异，但这就是两份文件手工 diff 时看起来比实际差异大得多的原因。

Scalar 还新增了 Stainless 没有对应物的键——diagnostics（按规范质量门禁构建）、ignoredEndpoints、customCasings、errors——第一天完全可以忽略。例如 ignoredEndpoints 用 "<verb> <path>" 形式（如 get /me）从生成中剔除端点；diagnostics 用 failOn、maxWarnings、rules 决定哪些诊断发现会让构建失败（详见 Diagnostics）。

一个值得手工验证的行为。 Stainless 按约定自动为名为 list_* 的方法启用分页，只有打破命名模式的方法才需要显式声明 paginated: true。因此，配置中隐含的分页是生成输出中最先要核对、而不是最后才核对的内容。

对照 Scalar SDK 配置参考 中的最小配置，可以直观看到目标格式的形态：

{
  "name": "Acme API",
  "environments": {
    "production": "https://api.acme.com"
  },
  "environmentOrder": ["production"],
  "targets": {
    "typescript": { "packageName": "@acme/api" },
    "python": { "packageName": "acme_api", "projectName": "acme-api" },
    "cli": { "binaryName": "acme" }
  },
  "resources": {}
}

其中 clientSettings 承载构造器选项、认证值、默认请求头、环境变量名、超时与重试（键为 camelCase，且构造选项可映射到 OpenAPI security scheme 或 server variable）；pagination 定义可复用的分页方案后在方法上以 paginated 引用；querySettings 与 multipartSettings 控制数组与嵌套对象的序列化。支持的目标键为 typescript、python、cli、go、rust、java、kotlin、swift、ruby、php、csharp、cpp、dart，设 skip: true 可保留配置而不生成。

一次迁移实际包含什么

针对 Scalar 的短版本流程：

1. 导出你的 OpenAPI 文档——如果你用过 openapi.transforms，请导出变换后的那份；
2. 原样取出仓库中的 stainless.yml——无需任何转换步骤；
3. 两者一起导入——在仪表盘中新建 SDK 时选择 Import config 上传，CLI 同样支持；
4. 对比 API 表面。 将生成的 api.md 与当前 SDK 的 api.md 做 diff。两者都按资源分组列出每个方法，diff 能立刻告诉你公开表面是否存活。重点核对：嵌套子资源的方法名、列表端点的分页（尤其是使用自定义 cursor 的）、客户端类名、以及你的用户传递凭据所用的环境变量名；
5. 接管管线。 卸载 Stainless GitHub App、接管 .github/workflows 中的发布工作流、重新指向注册表 token。

关于第 4 步，仓库的 Stainless 迁移指南 给出了更细的核对清单与背景。Scalar 的生成物与 Stainless 高度同构：资源命名空间化的方法、类型化错误（导出 BadRequestError、AuthenticationError、NotFoundError、RateLimitError 等层级）、自动分页、带 Retry-After 支持的重试，以及零运行时依赖——公开的 Warp TypeScript SDK 即携带 "dependencies": {}。迁移指南还提到，x-stainless-* 扩展 Scalar 会忽略无法识别的部分，留在文档中无害；若你在生成文件中编辑过代码，这些手写改动因 Stainless 的语义三方合并而与生成代码交错存放，再生成之前务必先识别出哪些文件带手写变更（Scalar 支持自定义代码与三方合并保留，见 custom-code）。

如果你不选 Scalar

无论最终选择谁，大部分工作都是一样的，其中一些无论决策耗时多久都值得本周就做：

• 趁还能再生成，立刻快照当前公开表面。 一份 api.md，或一个遍历已发布包并导出每个方法签名的脚本。没有它，你就无法证明迁移是非破坏性的，而且随着代码漂移，重建它只会越来越难。
• 在任何再生成之前，找出你的手写代码。 Stainless 通过语义三方合并把自定义代码并入生成文件，因此你的编辑与生成代码交错存放，而非独立补丁集。每个生成器处理方式不同；但如果你知道哪些文件受影响，所有生成器都会处理得更好。
• 如果你用过 Docs Platform，现在就把它从 stainless-sdks 组织迁出，哪怕还没决定文档下一步去哪。它是一次 fork 加一套 CI，趁源还在时做要容易得多。
• 向每个厂商问同一个问题：我现有的公开方法表面如何存活？ 要求对方给出"机制"而非"承诺"级别的答案。"我们会帮你迁移"和"我们读取你现有的配置"是截然不同的两种回答。
• 尽早决定 Terraform 的去留。 如果你原本就有 terraform 目标，这一点会最先收窄候选范围。
• 不要把"什么都没坏"当作时间。 时钟从你的下一次 API 变更开始计时，而只有你知道它何时到来。

获取帮助与时效性说明

如果你正在迁移且需要协助——包括最终选择了别的方案——可以预约 Scalar 团队沟通或免费开始使用。仓库也欢迎对文档内容的纠错：如果 The Stainless SDK generator wind-down 上关于你所在公司（或任何公司）的陈述有误、不公或已过时，可以通过仓库 Issues 提出，维护者会修正。

文中对 Stainless 及各家厂商的陈述，均以 2026 年 8 月 16 日对各厂商官网文档、定价页与仓库的调研为准；Stainless 于 2026 年 5 月 18 日宣布关停，其文档可能变更或下线，各家定价与功能集也在持续变动。全文做了如实呈现他人优势的努力——包括在多个维度上明确承认 Scalar 并非最优答案——请以仓库文档为基准并结合最新公开信息决策。若需要产品层面的逐项对比，可继续阅读 Scalar vs Stainless、Scalar vs Speakeasy 与 Scalar vs Fern。