Scalar vs Stainless：Stainless 停运后的 SDK 生成器能力对比与迁移承接-开发者社区

Scalar vs Stainless：Stainless 停运后的 SDK 生成器能力对比与迁移承接

【免费下载链接】scalarScalar is an open-source API platform: 🌐 Modern REST API Client 📖 Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar

本文是一份基于 Scalar 官方对比文档《Scalar vs Stainless》整理的技术指南。2026 年 5 月 18 日 Stainless 宣布并入 Anthropic 并逐步停运其托管产品（含 SDK 生成器），大批团队手中的 SDK 从此无法再重新生成。本文将从能力对比、stainless.yml兼容性、目标语言覆盖、文档与 Agent 支持四个维度展开，说明 Scalar 如何承接 Stainless 的用户面，并诚实指出其中 Scalar 并不占优的地方；文末给出可执行的迁移判断框架，配合仓库内 Stainless 迁移指南可直接落地。

本文由 Scalar 编写，立场上请自行判断。文中关于 Stainless 的事实均以其官方文档、定价页和公开仓库为准，Scalar 方面明确表示：若存在偏差，可提 issue 修正。

背景：一条改变整个对比的新闻

这份对比文档存在的前提，是 2026 年 5 月 18 日 Stainless 宣布并入 Anthropic、并停运所有托管产品——包括其 SDK 生成器。公告明确：新的注册、新项目和新的 SDK 生成已不可用。

因此，这不再是一个"两边都注册试用再比较"的选择题。但它仍然值得写，因为"和 Stainless 相比如何"是 Scalar 被问得最多的问题——Stainless 生成的 SDK 是开发者脑中默认的参照物，而现在大量团队手里握着一个无法再重新生成的 SDK。

仓库内 Stainless 停运全景分析对这次事件做了更细的拆解，其中三点值得先记住：

停运范围是所有托管产品，不只是 SDK 生成器，Docs Platform 也在其中；
新注册、新项目、新 SDK 在公告当天即关闭，不是未来某个时间点；
已经生成的代码归你所有——"你拥有迄今生成的所有 SDK，并拥有按其意愿修改和扩展的全部权利"。

对存量用户来说，今天没有任何东西会坏：已发布的包、仓库、手写代码都继续可用。真正停止的是"重新生成"——下一次 API 变更时，没有东西会自动更新。

一表速览：Scalar 与 Stainless 的关键差异

维度	Scalar	Stainless
接收新客户	是	否（2026 年 5 月起）
正式可用（GA）目标	TypeScript、Python、Go、CLI	TypeScript、Python、Go、Java、Kotlin、Ruby、PHP、C#
Terraform Provider 生成	无	有
MCP 服务器	有，托管且可配置	有，生成代码后自行部署
文档渲染器	MIT 协议，任意套餐可自托管	托管式文档平台
独立 API 客户端	有，开源	无
读取`stainless.yml`	是	是
已公布定价	每个套餐含一个目标，额外目标 $150/月起	已公布

从这张表可以立刻看出：Scalar 的定位不是"全面超越 Stainless"，而是在 Stainless 停运的时点上，尽量无缝承接它的用户面。表中两处"无"——Terraform Provider 和更多 GA 语言——是后面要重点展开的诚实缺口。

哪些地方 Stainless 确实更强

对比文档毫不回避地列出了 Stainless 的六项真实优势，这也是评估任何迁移方案时最容易被低估的部分。

规模效应与随之而来的成熟度。Stainless 官方声称其平台生成的 SDK 每周下载超过 1.3 亿次，用户包括 OpenAI、Cloudflare、Modern Treasury、Lithic、MUX、Replicate、Weights & Biases 等。多年流量意味着大量边界情况已被别人发现并修复。Scalar 的生成器更年轻，任何数量的测试都替代不了这种生产环境暴露——文档原话是"这是诚实的差距"。

更多越过实验线的语言。Stainless 提供 TypeScript、Python、Go、Java、Kotlin、Ruby、PHP、C# 共八种 GA 语言，另有 SQL 目标。Scalar 只有四种 GA 目标。特别值得注意的是，Stainless 是已知唯一把Kotlin 作为独立 SDK 而非 Java 包装的生成器——用可空类型替代Optional、用Sequence替代Stream、用suspend函数替代CompletableFuture。这是一种真正的设计投入，不是打勾。

Terraform Provider。Stainless 可从 OpenAPI 文档生成 Terraform Provider，Scalar 目前完全没有这个能力。如果你们的 API 是"基础设施"、用户以声明方式而非调用来使用，那么这一条就是整个对比的全部。Scalar 官方在停运全景分析中承认，Terraform 与 SQL 在路线图上但无发布日期，并明确建议有 Terraform 需求的团队直接去看 Speakeasy 的资料，而不是等 Scalar。

以代码形式交付、由你部署的 MCP 服务器。两者都做 MCP，但交付形态相反：Stainless 把 MCP 服务器生成为代码，支持 Docker 发布、远程部署、预注册应用的 OAuth 与按工具权限控制；Scalar 是托管形态（下文详述）。如果服务器必须跑在你自己的基础设施内，那一形态是 Stainless 的。

把设计决策写下来。Stainless 公开了多数厂商隐而不谈的取舍理由——例如为什么不做运行时请求校验、为什么 Kotlin 与 Java 是两套独立 SDK。Scalar 认为这是正确的做法，且承认自己公开发表的这类材料比 Stainless 少。

企业级深度。破坏性变更检测、SDK 版本固定、code owners、GitHub issue 自动分诊、SSO 与 SCIM——这些是成熟平台的可查证功能，Scalar 未在对比中声称等价。

为什么生成的 SDK 看起来如此相似

这是整份对比中最有用的一句话：Scalar 生成的输出刻意贴近 Stainless，文档没有回避这一点。

以错误处理为例。Stainless 的 TypeScript SDK 导出一整套错误层级：BadRequestError、AuthenticationError、PermissionDeniedError、NotFoundError、ConflictError、UnprocessableEntityError、RateLimitError、InternalServerError，外加连接与中止错误。Scalar 生成的客户端导出同名错误，公开 Warp SDK 中可见：

import { APIError, NotFoundError, RateLimitError } from "warp-hr"; try { const list = await client.customWorkerFields.list(); } catch (err) { if (err instanceof RateLimitError) { // 429，可类型化访问 status、name 和 headers } if (err instanceof APIError) { console.log(err.status, err.name, err.headers); } throw err; }

同样的收敛还体现在资源命名空间方法、自动分页、Retry-After处理、按请求的原始响应访问，以及零运行时依赖（Warp 包发布时"dependencies": {}）上。

这不是巧合，也不是奉承。生成的 SDK 是公开的 API 契约，Stainless 确立的约定已被大量开发者的肌肉记忆掌握，为差异化而差异化只会伤害用户。

它还有一个非常实际的后果：你的调用点可以继续工作。Scalar 直接读取stainless.yml，因此资源、方法名、子资源、模型、分页方案和各语言包名会原样迁移，而不是从 OpenAPI 文档重新推导。只凭规范重新生成会得到一套不同的 SDK——新命名空间、新方法名，对每个已安装你包的用户都是一次破坏性变更。这正是离开 Stainless 时真正花钱的部分，也是 Scalar 为此而构建的部分。

stainless.yml 兼容性：键级映射

停运全景分析给出了两种配置的键级对照，佐证了上述"无需重写配置"的说法：

`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 取产品名，其余组织元数据无对应位置

明确无法迁移的部分包括：targets: terraform与targets: sql（Scalar 今日无对应物，路线图无日期）、openapi.transforms（Scalar 的openapi键只做 SDK 级覆盖、不重写输入文档）、edition（Stainless 固定配置 schema 版本，Scalar 无此概念）、readme（README 示例选择无对应），以及命名风格差异（Stainless 用snake_case，Scalar 用camelCase——纯外观差异）。

还有一个必须手工核验的行为：Stainless 默认对命名为list_*的方法自动分页，只有打破命名模式的方法才需要显式paginated: true。因此隐式分页是迁移后第一个要在生成产物中确认的东西。Scalar 的 SDK 配置参考中pagination一节完整列出了请求游标与响应items/next的声明方式，可作为核对基准。

如何测试，以及拿什么对标

Scalar 无法主张 Stainless 那样的生产流量暴露，因此文档明确列出替代方案——这部分在 SDK 生成器指南的"Tested against SDKs that ship"一节有同源描述：

对标一致性（parity）测试装置：克隆生产级 SDK 并固定在指定 commit，提取双方的公开面，只要在操作覆盖、线上报文形态（wire shapes）、union、enum、分页行为、必填性和参数位置任一维度出现漂移，就使构建失败；随后驱动双方客户端对录制好的 mock 逐一执行共享操作，并对实际发出的请求做 diff。
由于团队今天发布的 SDK 大量由 Stainless 生成，这个装置在实践中很大程度就是在拿 Scalar 的输出与 Stainless 的输出互测。文档的态度是"宁可直说，也不暗示这些约定是我们独立想出来的"。
GA 目标还带有端到端测试：每次变更都生成、构建并针对真实服务器运行；每个目标另有冒烟测试，对 mock 服务器逐个调用每个操作。

目标语言：一份诚实的清单

Scalar 的GA 目标只有四种：TypeScript、Python、Go 和 CLI。

实验性：Java、Kotlin、Ruby、C#。它们与 GA 目标位于同一持续集成矩阵，是最接近越线的四个，但标签存在自有其原因——官方建议在规划迁移前先沟通，而不是迁移之后再发现缺口。
可生成代码但需先沟通：PHP、Rust、Swift、Dart、C++。

SDK 生成器指南给出的目标与注册表对应关系如下：

状态	目标	包注册表
GA	TypeScript	npm
GA	Python	PyPI
GA	Go	Go modules
GA	CLI	npm 与 Homebrew
实验性	Java / Kotlin	Maven Central
实验性	Ruby	RubyGems
实验性	C#	NuGet
实验性	PHP	Packagist
实验性	Rust	crates.io
实验性	Swift	Swift Package Manager
实验性	Dart	pub.dev
实验性	C++	无标准注册表

如果你今天持有的是 Stainless 生成的 Kotlin、Java、C# 或 PHP SDK，这就是迁往 Scalar 最真实的摩擦点——文档建议在规划迁移之前提出来，而不是之后。

文档：渲染器归属与"同一构建"

Stainless 的文档平台是一个 Astro 项目，仓库托管在stainless-sdks组织名下而非你自己的组织，附带组件库、AI 聊天、自定义域名与分析。Stainless 对停运给出的官方指引是：把它 fork 出来，自行承担 CI、部署、域名和运维工作。

Scalar 的做法在两个方面不同，这两点对"该落哪边"的决策直接相关：

渲染器归你。API 参考渲染器采用 MIT 协议，任意套餐均可自托管。你可以获得主题与 CSS 变量、任意页面上的自定义 HTML/CSS/JavaScript，甚至可以把整个渲染器 fork 走。

文档与 SDK 出自同一次构建。在 Scalar 的生成器中，docs是与语言目标并列的构建目标。一次运行同时产出 SDK、静态 API 参考和openapi.augmented.json——即 SDK 赖以生成的精确产物。你的参考文档和客户端库不可能描述两套不同的 API。

Scalar 官方站本身（本对比页、定价页、指南、API 参考与博客）就是用单个scalar.config.json构建并托管在 Scalar Docs 上的。仓库内 SDK 配置参考展示了这个配置的最小形态：name、environments、environmentOrder、targets与resources构成骨架，clientSettings控制构造选项与认证，pagination声明可复用分页方案，diagnostics决定哪些生成告警会阻断构建。

Agents：MCP 服务器与 SDK 内嵌上下文

双方都把 Agent 消费当作一等公民，也都从 OpenAPI 文档生成 MCP 服务器。分水岭在于服务器跑在哪里。

Stainless 把服务器生成为代码：按工具权限、Docker 发布、远程部署、预注册应用 OAuth。你负责部署与运维。
Scalar 托管服务器：你在仪表盘中挑选哪些端点变成工具，为每个工具选择"仅查找"或"发起真实认证请求"，并把 API 凭据存在安装内、绝不下发到客户端。服务器运行在mcp.scalar.com，默认私有；团队内用 Personal Access Token 连接，团队外用 OAuth。另有独立的Docs MCP位于你的文档域名/mcp，用于搜索和阅读已发布文档。完整流程见 MCP 服务器指南。

需要说明的是，仓库内 MCP 服务器指南对两种模式有更细的阐述：工具的Search 模式只做查找、不向你的 API 发请求，Execute 模式发出真实认证请求；认证可配为Global（安装级存一份凭据，所有调用共用）或Passthrough（调用方在指定头/查询参数中自带凭据，Scalar 逐请求转发、不落盘）。

除此之外，Scalar 还在 SDK内部交付 Agent 上下文：一个SKILL.md、.claude/skills/下的自动发现入口、一份按资源分组列出所有方法的生成式api.md，以及openapi.augmented.json。这比 MCP 服务器的目标更窄——只是阻止 Agent 凭空发明一个不存在的方法名——但它是默认开启的，而不是一个需要单独配置的目标。

应该怎么选

如果你是从零开始，这其实不是选择题：Stainless 已不再接收新客户。

可以暂时留在 Stainless 的情况：SDK 稳定、API 不变、愿意观望。你拥有已生成的代码，没有任何东西会在某个截止日期坏掉。真正的问题只出现在下一次 API 变更时。

值得认真考虑 Scalar 的情况：想要同样的 SDK 约定但不想重写配置；想要文档与 SDK 由同一次构建产出；想要一个 MIT 协议、归自己所有的文档层（而不是维护一个 fork 出来的 Astro 项目）；或者想要一个与文档配套的真正的 API 客户端。

应该另寻他处的情况：依赖 Terraform Provider；依赖必须作为代码跑在自己基础设施内的 MCP 服务器；或者依赖生产级支持的 Kotlin、Java、C#、PHP SDK——这些是 Scalar 承认会过度推销自己的领域。仓库内的停运全景分析对整个候选池（OpenAPI Generator、Speakeasy、Fern、APIMatic、liblab、开源方案及 Scalar 自身）逐一评估，并指名了在各项上更胜一筹的工具。

如果决定迁移：五步路径

对比之外，仓库内的 Stainless 迁移指南提供了完整实操步骤，其核心思想是你不应重写任何东西：

导出 OpenAPI 文档——特别注意：若使用了 Stainless 的openapi.transforms，仓库中的文档可能并非 Stainless 实际生成的输入，应取转换后的输出，让两个生成器看到同一份 API；x-stainless-*扩展 Scalar 会忽略，可原样保留。
原样取走stainless.yml——它在你的仓库里有版本管理，无需转换、剥离或翻译。
导入 Scalar——创建新 SDK 时选择Import config，把 OpenAPI 文档与stainless.yml一起上传。
发布前验证——对比生成出的api.md与现有 SDK 的api.md，两者都按资源分组列出所有方法，diff 能立刻暴露公开面是否完整；重点检查嵌套子资源方法名、列表端点的分页（尤其自定义游标）、客户端类名与用户传凭据的环境变量。
从你自己的仓库发布——npm、PyPI、Maven、RubyGems 包名与注册表不变，用户的安装路径不变；变化的是推送方：卸载 Stainless GitHub App、接管.github/workflows中的发布工作流、把注册表令牌重新指向 Scalar 的发布流程。Scalar 通过向你仓库开 pull request 来发布，发布始终可审查。

关于手写代码：Stainless 通过语义化三方合并把定制代码交织进生成文件而非单独保存，因此迁移前先识别哪些文件带手写改动，会大幅降低再生成本。Scalar 支持自定义代码，并提供了显式标记区域以在每次再生时保留（见自定义代码指南）。

定价参考

Scalar 的 SDK 定价按包含的端点规模计：每个套餐含一个 SDK 目标，Pro 每额外目标 $150/月、Business 每额外目标 $600/月（有量级折扣）；免费档含 1 个目标、上限 25 个端点，Pro 100 端点，Business 250 端点，Enterprise 定制。目标在"保存版本并排队构建"时才开始计费，草稿不计费。详细对照见 SDK 生成器指南的 Plans 一节。

本对比基于 2026 年 8 月时 Stainless 公开的文档、定价页与公开仓库，以及 Scalar 自身的源码与生成产物。Stainless 于 2026 年 5 月宣布停运，其文档可能变更或撤下，部分链接可能失效。Scalar 官方声明：已尽力保证准确并如实指出 Stainless 更强的领域；若发现错误或过时内容，可在其仓库提交 issue 以便修正。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考