Scalar 视角下的 Stainless SDK 生成器停运：从方案评估到 stainless.yml 兼容迁移的完整指南

本文是技术迁移决策指南，主体素材来自仓库文档 documentation/resources/stainless-wind-down.md，并结合 迁移实战指南、产品对比、SDK 配置参考 与 SDK 生成器总览 展开。2026 年 5 月 18 日，Stainless 宣布并入 Anthropic 并停运其全部托管产品，包括 SDK 生成器。本指南为你梳理"到底什么变了、你被迫要做哪些决定、现实选项有哪些"，并给出以 Scalar 为例的完整迁移路径——包括 stainless.yml 的字段级兼容映射与迁移后的逐项验收方法，读完你可以在自己的时间表上完成一次不破坏既有调用方代码的 SDK 生成器迁移。

事件背景：2026 年 5 月 18 日到底发生了什么

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."

（"随着我们聚焦 Claude Platform 能力与连接 agent 与 API，我们将停运全部托管 Stainless 产品，包括 SDK 生成器。从今天起，新注册、新项目和新的 SDK 将不再可用。"）

这段话里有三件事容易混为一谈，但每一件都影响你的决策：

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."

（"一如既往，你拥有迄今生成的所有 SDK，并拥有按其意愿修改和扩展它们的全部权利。"）

Stainless 将存量客户引导到 app.stainless.com/transition 页面；该页面需要登录账号才能看到，因此如果你有账号，应在参考本文之前先读那个页面。

Stainless 没有公布的一件事：存量项目的结束日期。 公告只覆盖了新注册、新项目和新 SDK，并未说明存量项目的构建何时（或是否）停止。原文档明确表示不会替 Stainless 猜测这一日期：如果你需要据此做规划，应当把"没有公布日期"当作"按自己的节奏迁移"的理由，而不是"可以继续放心用"的保证。

研究日期：2026 年 8 月 16 日（以仓库文档标注为准）。如果 Stainless 后续公布了时间线，本文内容可能已过时。

如果你今天仍在使用 Stainless：哪些继续可用，哪些停止

今天什么都不会坏。 这一点是真实的，但也正是它让这件事容易被一拖再拖。

继续可用的部分：

• 你已经发布的所有包。用户仍会安装他们现在安装的版本，行为完全不变。
• 你组织名下的 SDK 仓库与各类 registry 上的发布物。
• 其中每一行生成代码和手写代码——它们归你所有。

停止的部分：

• 重新生成。 下一次你新增端点、修改响应结构或废弃字段时，没有任何东西会自动更新。
• 新增一种你没有生成过的语言。
• Docs Platform（如果你在用）。 Stainless 将这些仓库存放在 stainless-sdks GitHub 组织下而非你的组织，Stainless 自己的托管指引是：把 Astro 项目 fork 出去，由你自己接管仓库、CI、部署与域名——之后"你的组织对仓库、CI 配置、部署目标、域名配置及其他运维事项负全责"。

所以真正的截止日期不是 Stainless 的，而是你下一次 API 变更。 在那之前，什么都不做的成本是零；在那之后，你的 SDK 与你的 API 开始不一致，且差距随每次发布越来越大。

评估任何替代方案之前：先理解为什么 OpenAPI 文档不是难点

面对这种情况，最直观（也最昂贵）的读法是："我有一份 OpenAPI 文档，每个生成器都读 OpenAPI，所以我可以随便挑一个。"

这个想法会让你付出最大代价。原因在于：

你的 OpenAPI 文档从来不是难点。 它属于你、可移植、描述你的 API。但它不描述你的 SDK：哪些 operation 变成了哪些命名空间、每个方法叫什么、每个 list 端点用哪种分页方案、client 类叫什么、每种语言里包名叫什么。这些决策都活在 stainless.yml 里，没有一项可以用 OpenAPI 表达。

如果只用规范重新生成，无论用哪个工具，你都会得到一个公共表面（public surface）不同的可用 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 和契约测试。它在这个品类里的资历与 Stainless 相当。

Speakeasy 胜过 Scalar 的地方： Terraform provider 生成。Stainless 有 terraform target，而 Scalar 没有对应物。如果你正在从 API 描述生成 Terraform provider，Speakeasy 是直接答案，这一点无须粉饰。此外它还生成 MCP server 和契约测试，其对比类与技术选型类的公开写作是该品类最详实的材料——即便出自我们的竞对，也值得一读，原因与你应该带着怀疑读本文一样。

披露： Scalar 与 Speakeasy 存在合作。Speakeasy 文档中记录了一个 Scalar 集成，把其自动生成的代码示例接入 Scalar 渲染的 API 参考。阅读我们对它的评价时请把这点也考虑进去——两个方向都是。

值得了解： 免费档覆盖 1 个 SDK、最多 50 个 API 方法，付费档提供 14 天试用；其定价页目前主打 MCP 与 AI 产品而非公开的 SDK 价目表，所以拿到确切报价大概率要与销售沟通。Speakeasy 通过自己的 gen.yaml 与 workflow 文件配置，没有 stainless.yml 导入能力，因此保留既有公共表面是需要自行评估工作量的手工活。更完整的对比见仓库的 Speakeasy 对比文档。

Fern

Fern 于 2026 年 1 月被 Postman 收购，并声明产品与品牌将继续独立运营。Fern 发布过面向 Stainless 客户的迁移号召，并提供迁移协助。

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

值得了解： Fern 的迁移材料是"承诺帮助"而非"文档化的机制"——截至撰写时它没有描述如何读取 stainless.yml 或复现你现有的方法名。在投入之前直接问他们：你的公共表面如何被保留。Fern 免费 SDK 档上限为 50 个端点，大量 SDK 功能标记为 Enterprise-only，按 SDK 计价、按年计费且无公开价目。更详细的分析见仓库的 Fern 对比文档。

APIMatic

这个品类里运营时间最长的商业生成器，也是价格最透明的：支持 7 种语言并发布价目表——Lite 档 $10/月（1 种语言、每个 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 解析为已解析的中间表示，而不是开箱即用的生成器——emitter 由你编写。适合那些已经决定要完全自建生成管线、且不想从 Mustache 模板起步的团队。

Scalar 在这个场中的位置

原文档这样陈述 Scalar 的答案（以便读者可以恰当地对其打折）：

• Scalar 生成 TypeScript、Python、CLI、Go、Rust、Java、Kotlin、Swift、Ruby、PHP、C#、C++ 和 Dart。每个套餐包含 1 个 target，额外 target 每个 $150/月起、价格公开。SDK 位于你的仓库、使用你的包名——Scalar 以 pull request 方式向你的仓库提交代码，绝不会替你打 tag。
• Scalar 还从同一份 OpenAPI 文档构建 MCP server，支持按端点选择工具、存储的认证以及面向团队外成员的 OAuth。Scalar 托管这些 server 而不是生成一个由你自己部署的 server——这与 Speakeasy 的取舍相反：他们给的是你拥有并运行的代码，Scalar 给的是你配置、Scalar 运维的端点。如果"自己运行"是硬性要求，那是 Speakeasy 的得分点。
• 在这种局面下看 Scalar 的具体理由：Scalar 把 stainless.yml 作为输入直接读取。 这不是泛泛的优越性声明，而是一个恰好在此刻极为重要的结构性事实——这正是下一节的主题。
• Scalar 落后的地方： 没有 Terraform 或 SQL target，没有 gRPC/AsyncAPI/OpenRPC 输入，生成器本身不开源。其 target 中 TypeScript、Python、Go 和 CLI 为一般可用（generally available），其余标记为实验性。如果你的迁移依赖某个实验性 target，请在做规划前先沟通，而不是规划之后。Terraform 和 SQL 在 Scalar 的路线图上——这是关于计划的陈述，不是对缺口的回答：没有发布日期，如果你现在就有 terraform target，应该去读 Speakeasy 的材料而不是等 Scalar。

仓库的 Scalar vs Stainless 对比文档 提供了逐项对照，包括 Stainless 真正更强的部分（规模与随之而来的成熟度、Kotlin 作为独立 SDK 而非 Java 包装、企业级深度如 breaking change 检测、固定 SDK 版本、SSO/SCIM 等）。

stainless.yml 兼容性：字段级映射与不兼容清单

"无缝迁移"是任何人不应该不做核验就接受的声明。两个配置描述的是同一类东西——资源树、targets、分页方案、client 设置——所以映射大多是机械性的。差异真实存在但可点名。对照 Stainless 的配置 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 用于许可（licensing），Scalar 用于文件头与响应解包。
organization	name	Scalar 取产品名；Stainless 其余组织元数据没有直接落点。

明确无法迁移的部分：

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

Scalar 还增加了 Stainless 没有对应物的键——diagnostics（用规范质量来门禁构建）、ignoredEndpoints、customCasings、errors——这些在迁移第一天完全可以忽略。其中 diagnostics 支持 failOn（off/info/warn/error，默认 error）、maxWarnings、maxErrors、按规则 id 覆盖严重度的 rules 与按规则抑制的 ignored，详见 配置参考。

一件值得手工核验的行为。 Stainless 按约定自动为名为 list_* 的方法开启分页，只有打破命名模式的方法才需要 paginated: true。你配置中隐含的分页是生成结果里第一个要核验的东西，而不是最后一个。Scalar 侧的分页方案定义（以 cursor 为例）大致如下，可在配置编辑器中对照：

{
  "pagination": [
    {
      "name": "cursor",
      "type": "cursor",
      "request": {
        "cursor": {
          "type": "cursor",
          "param": "cursor",
          "location": "query"
        }
      },
      "response": {
        "items": {
          "type": "items",
          "location": "body",
          "path": ["data"]
        },
        "next": {
          "type": "cursor",
          "location": "body",
          "path": ["next_cursor"]
        }
      }
    }
  ]
}

一次真实迁移的五步走（以 Scalar 为例）

迁移指南（documentation/migration/stainless.md）将完整流程压缩为五步，核心理念是：你不应该重新编写任何东西——把 OpenAPI 文档和 stainless.yml 交给 Scalar，它从你已有的配置生成。

第 1 步：导出你的 OpenAPI 文档

这份文档你本来就有。需要先检查一件事：如果你用过 Stainless 的 openapi.transforms，仓库里的文档可能不是 Stainless 实际生成所依据的文档——请取 transformed 后的输出，让两个生成器看到同一份输入。同时留意 x-stainless-* 扩展：Scalar 会忽略它不认识的扩展，留在原地也无害。

第 2 步：原样取走你的 stainless.yml

它版本控制在你自己的仓库里。直接复制，无需转换、无需删减、无需先翻译成 Scalar 格式。没有中间格式、没有配置重写、不需要手工重新映射 API 表面。

第 3 步：导入 Scalar

新建 SDK 时选择 Import config，把 OpenAPI 文档与 stainless.yml 一起上传。Scalar 读取配置、映射到自己的生成器、为已配置的 targets 产出 SDK。CLI 同样接受这种导入方式。

第 4 步：发布前认真验收——这一步保护的是你的用户

比较生成的 api.md 与当前 SDK 的 api.md。两者都按资源分组列出每个方法，因此 diff 能立刻告诉你公共表面是否完好。重点检查：

• 嵌套子资源上的方法名
• list 端点的分页，尤其是任何使用自定义 cursor 的
• client 类名，以及用户传入凭据的环境变量名

如果有对不上的地方，反馈给 Scalar 修复映射——这比绕开它工作更快。

第 5 步：从你自己的仓库发布

你的生产仓库本来就是你的，npm、PyPI、Maven、RubyGems 包也是你的。迁移不改变包名和 registry，用户继续安装他们今天安装的东西。改变的是谁向仓库推送：

• 卸载 Stainless GitHub App
• 接管 .github/workflows 中的发布 workflow
• 把 registry token 重新指向 Scalar 的发布流程

Scalar 通过向你的仓库发起 pull request 来发布，因此每次发布都可审查。

Scalar 生成的东西长什么样

下面是迁移指南中给出的真实生成 TypeScript 代码（来自公开的 Warp SDK 的生成产物）：

import WarpAPI from "warp-hr";

const client = new WarpAPI({
  apiKey: process.env["API_KEY"], // defaults to the API_KEY env var
});

const list = await client.customWorkerFields.list();

错误是类型化的，status 集合由你的规范生成：

import { APIError } from "warp-hr";

try {
  const list = await client.customWorkerFields.list();
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.name, err.headers);
  }
  throw err;
}

从 Stainless 迁移过来的开发者会感到熟悉：资源命名空间化方法、类型化错误、自动分页、支持 Retry-After 的重试、零运行时依赖（除非你启用了需要依赖的功能——Warp 包就带着 "dependencies": {}）。这种相似不是巧合也不是恭维：生成的 SDK 是一份公共 API 契约，Stainless 确立的约定是大量开发者已经熟记的，为差异而差异只会让用户买单——它带来的实际结果是你的调用点继续可用。

迁移中必须处理的三类特殊资产

自定义代码（custom code）

如果你编辑过生成文件，这些编辑是仓库里的普通提交——Stainless 通过语义三方合并（semantic three-way merge）应用它们，因此你的修改与生成代码交错存放，而不是作为独立的补丁集。重新生成之前，先识别哪些文件带有手写变更。Scalar 同样支持自定义代码：每次构建都在"上一次生成 / 新一次生成 / 仓库当前状态"之间做三方合并，再开一个合并两者的 pull request——未改动的文件干净更新、你的编辑随之保留、你自己新增的文件不受触碰。想显式固定一段代码，用标记区域：

// scalar-sdk-generator:custom-code retry-helper:start
export const withBackoff = async <T>(fn: () => Promise<T>) => {
  // Anything in here is carried forward on every regeneration.
};
// scalar-sdk-generator:custom-code retry-helper:end

只有重新生成的文件恰好在同一行上也改了才会冲突，此时冲突以 pull request 形式出现在 GitHub 上，按普通合并冲突解决。整个过程跑在可审计的托管分支上：scalar-generated（纯净输出）、scalar-next（与你的提交合并）、scalar-merge-conflict（需要人工介入的部分）。

Docs Platform

Stainless 的文档平台是一个 Astro 项目，仓库在 stainless-sdks 组织下而不是你的组织。Stainless 自己的指引是 fork 出去，自己承担 CI、部署、域名与运维。如果不想自己运行它，Scalar Docs 从同一份 OpenAPI 文档渲染 API 参考，并支持 Markdown 与 MDX 指南，用 scalar.config.json 控制导航与主题。

Terraform / SQL 目标

如果你有 terraform 或 sql target，这会最先收窄你的选项。Scalar 目前没有对应物（路线图无日期），Speakeasy 与 liblab 都支持 Terraform provider 生成——尽早做这个决定。

如果你最终不选 Scalar：现在就该做的六件事

无论选谁，大部分工作是一样的，其中一些无论你花多久做决定，都值得本周就做：

1. 现在就给你的公共表面拍快照，趁还能重新生成。 一份 api.md，或一个遍历你已发布包、导出每个导出方法签名的脚本。没有它，你无法证明迁移是非破坏性的，而且随着代码漂移，事后重建会越来越难。
2. 在重新生成任何东西之前，找出你的手写代码。 Stainless 通过语义三方合并把自定义代码并入生成文件，你的编辑是交错的、不是独立的补丁集。每个生成器处理方式不同，但如果你提前知道哪些文件受影响，所有生成器都会处理得更好。
3. 如果用过 Docs Platform，现在就把仓库从 stainless-sdks 取出来，哪怕你还没决定文档下一步去哪。它就是一个 fork 加一套 CI，趁源还在时做严格意义上更容易。
4. 向每个厂商问同一个问题： 我现有的公共方法表面如何存活？要求以机制（mechanism）而非承诺（commitment）的形式回答。"我们会帮你迁移"和"我们读取你现有的配置"是完全不同的两个答案。
5. 尽早决定 Terraform 的去向。 如果你有 terraform target，它在任何其他决策之前就先收窄了候选范围。
6. 不要把"什么都没坏"当成时间。 倒计时从你下一次 API 变更开始，只有你知道它什么时候来。

延伸阅读（仓库内路径）

• Stainless 迁移完整实战指南——含导入步骤、验收清单、发布接管与自定义代码处理
• Scalar vs Stainless 产品对比——逐项对照，包括 Stainless 真正更强的部分
• Speakeasy 对比 与 Fern 对比——两大商业竞对的详细评估
• SDK 配置参考——targets、resources、clientSettings、pagination、diagnostics 等全部字段说明
• SDK 生成器总览——支持的语言与 registry、一般可用/实验性状态、自定义代码三方合并机制
• MCP Server 指南——从同一份 OpenAPI 文档构建 MCP server 的托管方案

本文事实依据截至 2026 年 8 月 16 日（仓库文档标注的研究日期），对应 Stainless 的公告与其自身文档、以及各家厂商的公开文档/定价页/仓库。Stainless 于 2026 年 5 月 18 日宣布停运，其文档可能变更或被撤回，厂商定价与功能集也在变动。文中同时陈述了 Scalar 落后于各选项的地方——包括 OpenAPI Generator、stainful 这类免费开源方案——请在决策时自行权衡。