这篇文章最初发表在SpecShield博客上。我是SpecShield的联合创始人之一，SpecShield是下面讨论的迁移目标之一——坦白说。这篇文章试图诚实地说明SpecShield的定位以及其他工具更适合哪些方面.

TL;DR

• Optic的GitHub仓库在2026年1月12日被归档。最后一次发布：v1.0.9 将在2025年8月推出。useoptic.com域名已不再解析.
• Optic 在2024年4月被Atlassian 收购，但从未整合到 Atlassian Compass.
• MIT许可的源代码仍然在GitHub上，但已废弃— 没有安全补丁，没有新规则，没有支持，当传递依赖项达到生命终结时，你的持续集成系统最终会崩溃。
• 如果你主要使用OpticCI中的规范差异比较和破坏性变更检查, 最直接的迁移路径是到SpecShield(SpecShield)（Web UI + CLI + GitHub App + 免费GitHub Action）或者oasdiff (开源命令行工具，无界面)
• 如果你使用 Optic 进行 从测试流量生成 OpenAPI — 没有直接替代方案。你需要更改工作流程.
• 以下：一个按功能比较的表格，一个逐步迁移指南，以及一个诚实地列出难以替代的内容的清单.

Optic 实际上发生了什么

过去六年，Optic一直是OpenAPI版本变更检测的开源首选。它拥有大多数开发者工具初创公司所不具备的东西：简洁的命令行界面、合理的规则系统、MIT许可证、深入的持续集成整合，以及一个虽小但忠诚的社区。

以下是它终结的时间线：

没有正式的停用公告，没有来自Optic团队的迁移指南，也没有存档但这里有一个分支的祝福。它就这样停止了.

在Atlassian收购后，社区中的期望是Optic将成为Atlassian Compass的一部分 — Atlassian 的开发者体验产品。那次集成从未发布。截至 2026 年 5 月，Compass 仍专注于服务目录和 DORA 指标，没有 API 分叉检测功能.

这个 1.5k 星的仓库有 92 个分叉，但 没有分叉成为社区中的后继者。如果你继续依赖@useoptic/optic，你依赖的代码将最终在 TypeScript / Node / npm 依赖版本到期时失效。

你需要迁移。好消息：这对大多数团队来说是一项四小时的工作，而不是一个四周的项目。

你实际使用的 Optic（以及你需要替换的部分）

Optic 有五种不同的功能。不同的团队使用了不同的子集。在挑选替代品之前，先确定哪些功能适用于你——选错是迁移过程中最大的错误.

1. 逐项差异比较和破坏性变更检测

最常见的用例。你的代码库中有了 openapi.yaml，你运行optic diff 在每次 PR 上进行 CI，并且该操作在 PR 上评论了破坏性变更警告。

替换难度： 容易。存在多个即插即用的替代方案。

2. 基于规则的 OpenAPI 代码检查

Optic 拥有自己的规则集格式 (.optic.dev.yml)，用于类似“所有路径必须是 kebab-case”或“每个端点都需要描述”的情况。

替换难度： 中等。您将切换到 Spectral，这是 OpenAPI 校验的事实标准，并且拥有更庞大的规则集生态系统。您的自定义规则需要以 Spectral 的格式重新表达。

3. 从捕获的流量生成 OpenAPI (optic capture)

这是Optic最新颖的功能。你会在你的测试套件前面运行Optic代理，然后Optic会根据观察到的流量生成（或更新）OpenAPI规范.

替换难度：困难。没有直接的开源替代品具有相同的成熟度。替代方案包括：

• Pollyjs（记录/回放HTTP，通用）
• Speakeasy (不同的工作流程——规范驱动SDK，而不是流量驱动规范)
• 手动维护OpenAPI规范（这是大多数团队最终会做的事情)

如果你严重依赖optic capture，你的迁移比spec-diff用户更痛苦。相应地计划.

4. 通过GitHub Action进行CI集成

useoptic/optic-action GitHub Action 提交了 PR 评论并附带差异结果。

替换难度： 容易。存在多个即插即用的替代方案，具有相似或更好的 PR 评论设计。

5. 用于浏览差异和历史记录的托管 UI

Optic Cloud（SaaS 层）为你提供了一个用于跨版本浏览差异并与非开发人员利益相关者共享的 Web UI。

更换难度： 中等。目前市面上的托管式 UI 工具要么价格更高（Bump.sh、Stoplight），要么看起来不够精致。SpecShield 的网络 UI 在范围上是一个直接对应，并且正在积极开发中。

您的迁移选项一览

截至 2026 年 5 月的实用替代方案的真实比较：

三种模式将覆盖 ~95% 的 Optic 迁移：

1. 您在 CI 中使用 Optic 进行 spec-diff + 您需要 UI → SpecShield (最直接的替代品，最小的思维模型转变)
2. 您在 CI 中使用 Optic 进行 spec-diff + 您不需要 UI → oasdiff (仅限 CLI，Apache 2.0 许可，将比任何 SaaS 公司存活得更久)
3. 您在 CI 中使用 Optic 进行代码检查 → Spectral（无论你选择哪种差异工具）

本文档其余部分专注于路径 #1，因为它是最常见且最缺乏文档的。如果你在路径 #2 或 #3 上，oasdiff 和 Spectral 的官方文档非常出色，你不需要迁移指南。

为什么 SpecShield 是 Optic 用户的最佳直接替代品

我专门为 Optic 倡导的以规范为先、持续集成驱动的流程构建了 SpecShield。心智模型完全相同：

• 你将你的 OpenAPI 规范提交到 git
• 在每次 PR 中，新的规范与主分支进行比较
• 在合并前标记出破坏性变更
• 您得到一份漂亮的差异报告（在界面中，在命令行中，）和作为公关评论)

与Optic相同的是什么？

• OpenAPI 3.0 和 3.1 支持
• 多文件规范支持（与$ref)
• 重大变更分类（已移除路径、类型变更、新增必填字段等）
• 通过 GitHub 应用和（即将）免费的 GitHub Action 进行 CI/CD 集成
• 通过 npm 分发 CLI (npx specshield compare ...)

比 Optic 更好的是什么：

• 双向契约测试 (BDCT) — 验证提供者/消费者兼容性，并带有 can-i-deploy 阈值。Optic 从来都没有这个功能.
• 兼容性矩阵 用于多服务架构
• 美丽，值得截图的 PR 评论 (Optic 的设计是功能主义的)
• 活跃开发 — 我们大约每周发布一次
• 免费层 无时间限制 (Optic Cloud 的免费层一直有限制)

有什么不同 (一些团队会认为这是降级):

• SpecShield 是一款拥有免费层级的 SaaS 产品。如果你使用的是开源 CLI，Optic 需要自带基础设施.
• 核心差异引擎目前不是开源的（免费的 GitHub Action 将会在 2026 年稍晚时候发布）。
• 我们的团队规模比 Optic 在巅峰时期要小——尽管我们发布速度更快.

如果你主要是因为 Optic 停止维护而你想要一些将进行维护，那些权衡可能对你有利。如果你根本只需要开源软件，请查看oasdiff.

分步迁移：Optic → SpecShield

这是使用Optic的CLI和GitHub Action的团队的实际迁移。预计整个过程（包括PR审核时间）需要30-60分钟.

第0步 — 审计你当前使用的内容

删除任何内容之前，在您的代码库中找到所有引用 Optic 的地方：

# Find Optic config files
find . -name ".optic.dev.yml" -o -name "optic.yml" -o -name ".optic*"

# Find Optic CI workflows
grep -rE "useoptic/optic-action|optic diff|optic lint" .github/

# Find Optic CLI invocations in scripts
grep -rE "@useoptic/optic|optic capture|optic verify" package.json scripts/

# Find references in docs
grep -ri "optic" README.md docs/ 2>/dev/null

列出您找到的每个文件。您将逐一处理它们.

第一步 — 安装 SpecShield CLI

SpecShield CLI 已发布到 npm 作为 specshield。您不需要全局安装它 —npx 适用于持续集成：

# Test it locally — no signup needed for the diff command
npx specshield compare old-openapi.yaml new-openapi.yaml

您将看到输出，其中包括与 Optic 生成的相同类别（断行、非断行、新增），格式化为干净的终端表格.

如果您想要用于持续集成脚本处理的 JSON 输出，请使用 --json 标志（与 --output 结合使用以同时写入文件）：

# Print JSON to stdout AND save to a file
npx specshield compare old.yaml new.yaml --json --output diff.json

JSON 结构如下：

{
  "summary": { "breaking": 3, "additions": 12, "modifications": 7, "warnings": 0 },
  "breakingChanges": [...],
  "additions": [...],
  "modifications": [...],
  "warnings": [...]
}

第 2 步 — 替换你的 Optic GitHub 工作流

如果你有类似这个.github/workflows/api-check.yml的东西：

# OLD — Optic workflow
name: API contract check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: useoptic/optic-action@v1
        with:
          spec: openapi.yaml
          base_ref: ${{ github.event.pull_request.base.ref }}

用这个替换：

# NEW — SpecShield CLI workflow
name: API contract check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Extract base spec from base branch
        run: git show origin/${{ github.event.pull_request.base.ref }}:openapi.yaml > /tmp/base.yaml

      - name: Compare specs
        id: compare
        continue-on-error: true
        run: |
          {
            echo '## 🛡️ SpecShield · API contract check'
            echo ''
            echo '```
{% endraw %}
'
            npx specshield compare /tmp/base.yaml openapi.yaml --fail-on-breaking
            echo '
{% raw %}
```'
          } > /tmp/comment.md

      - name: Comment on PR
        if: always()
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: /tmp/comment.md

      - name: Fail the build if breaking changes were found
        if: steps.compare.outcome == 'failure'
        run: exit 1

关于这个模式的几点说明：

• CLI 在非 TTY 环境下会自动禁用 ANSI 颜色代码，所以代码块内的输出在 GitHub 上能正常显示。
• continue-on-error: true 在比较步骤中允许在检测到破坏性变更时发布 PR 评论。最终步骤会明确地让构建失败，以便 PR 检查仍然可以阻止合并。
• marocchino/sticky-pull-request-comment 在后续提交时更新现有的评论，而不是在 PR 中进行垃圾信息轰炸。
• 一个专门的SpecShield操作（正在开发中）将渲染一个更丰富的markdown评论，包含颜色编码的摘要表和可折叠的每个端点的差异。在那之前，上面提到的围栏代码块方法是最干净的路径.

第3步 — 迁移你的自定义规则（如果你有的话）

如果你自定义了Optic的规则引擎，这一步会花费最长的时间。Optic规则看起来是这样的：

# OLD — .optic.dev.yml
ruleset:
  - breaking-changes
  - examples
  - name: kebab-case-paths
    where:
      operation: { in: any }
    rule:
      after: must
      assert: |
        operation.path.split('/').every(s => /^[a-z0-9-]*$/.test(s))

SpecShield 目前没有提供 Spectral 兼容的自定义规则 API。暂时：

• 破坏性变更规则：由 SpecShield 的内置检测器覆盖 — 无需迁移
• 样式/代码检查规则（使用连字符命名路径、需要描述等）：将这些迁移到 CI 中的单独 Spectral 步骤：

- name: OpenAPI lint
  run: npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml

使用类似.spectral.yaml的：

extends: spectral:oas
rules:
  paths-kebab-case:
    description: Paths should be kebab-case
    given: $.paths.*~
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: ^(\/[a-z0-9-]*)+$

我们正在为SpecShield开发一流的定制规则支持。在那之前，上述的两步方法是最干净的路径.

第4步 — 移除Optic依赖

一旦你的新工作流变为绿色：

# Remove npm dep
npm uninstall @useoptic/optic

# Remove config
rm .optic.dev.yml

# Remove the old workflow (or just edit it)
rm .github/workflows/optic-check.yml

将迁移作为一个单独的PR提交 — 更容易审查，如果有什么不对劲的话也更容易回滚。

第 5 步 — 设置仪表板（可选但推荐）

如果您需要历史记录、团队协作、BDCT 以及超出每个 PR 差异的其他 can-i-deploy 门禁：

1. 在 specshield.io
2. 在您的仓库上安装 SpecShield GitHub 应用程序
3. 您现有的 CLI 运行将自动出现在您的仪表板的比较历史记录中

无需重新配置 — GitHub App 和 CLI 写入相同的后端.

SpecShield 不取代 Optic 的哪些功能（坦诚地说）

当今有三个 Optic 功能没有干净的 SpecShield 替代方案。如果你依赖这些功能，你需要一个计划.

1. optic capture — 从流量生成规范

SpecShield 中没有直接替代方案。 我们的模型假设您手动维护规范（或通过框架注解库从代码中生成）。如果 optic capture 对您的工作流程至关重要，请评估：

• 继续使用 Optic 的存档 capture 独立命令（它将暂时继续工作——它不依赖于网络）
• 替换为 Pollyjs 用于记录/回放
• 转向以规范优先的工作流程（尽管行业已经朝着这个方向发展，但这也只是个时间问题）

optic capture-风格的功能在我们的路线图中，但不会在2026年发布.

2. MIT许可的核心

Optic的diff引擎是MIT许可的。SpecShield的核心引擎从2026年5月开始是闭源的。免费的GitHub Action将在发布时采用Apache 2.0许可，但托管产品背后的引擎是专有的。

如果"必须完全开源"是不可协商的要求，请使用oasdiff——这是最成熟的开源选项，并且不受Optic停运的影响.

3. 规则集的确切格式

Optic的规则DSL是独特的。你的规则不能1:1地迁移到任何其他地方。你将在以下两种情况之一中重新编写它们：

• SpecShield内置规则（默认覆盖约80%的常见情况）
• Spectral的规则DSL（用于剩余20%的自定义样式规则）

为每个自定义规则的重写计划约1小时

当SpecShield不是合适的迁移目标时

在另一款工具更合适的情况下提供的真诚建议：

对Optic时代之后的现状的诚实解读：没有单一的工具能涵盖Optic所做的一切。大多数团队最终会在他们的工作流程中使用两个工具——一个用于差异/破坏性变更检测，一个用于代码风格检查——而之前他们只有一个。

从Optic的终结中学到的

一些值得深思的启示，特别是如果你构建或支付开发者工具的话：

1. 开源软件+风险投资是一个脆弱的组合. Optic获得融资，被收购，并在典型的风险投资基金生命周期内关闭。开源代码仍然存在，但没有人付费来维护它。如果一个工具对你的持续集成至关重要，请考虑其资金模式和可持续性以及其功能.

2. 收购不等于持续运营。 "被[BigCo]收购"在当时听起来让人安心。但几乎从不如此。除非被收购工具的产品路线图公开与收购方的既定方向一致，否则要为它在18个月内消失做准备.

3. 先关注规范。 Optic 的赌注是你应该从流量中自动生成规格。行业共识已经转向了另一边——规格是真相的来源，代码和测试是从它生成的。这种转变是导致从捕获中生成规格的方法没有成为不可或缺的部分的部分原因.

4. 美观很重要。 Optic 的公关评论虽然实用但很普通。现在取代它的工具（以及那些将取代它们的工具）在 UI/UX 方面竞争激烈。工程师们截屏并分享看起来不错的评论。这就是传播.

今天迁移，不要等到下个季度

进行这次迁移的三个原因 现在 ，而不是在下个发布之后：

1. Optic 的 npm 包最终会失效。 @useoptic/optic 依赖于 TypeScript、Node 以及数十个传递性包，其中一些将在 12 个月内达到 EOL（结束生命周期）。当这种情况发生时，你的 CI 将在难以调试的方式下开始无声地失败，因为底层工具不再维护。

2. 你的团队正在忘记 Optic 的怪癖。 你等待得越久，迁移就越困难。设置你光学工作流的工程师可能在12个月内不在公司了。

3. 如果你现在进行迁移，那就很简单。 大多数团队可以在不到一个小时的时间内完成上述步骤。等到CI中断迫使你动手，你会在周五下午手忙脚乱地进行。

5分钟内试试SpecShield。

如果你已经读到这，并想尝试将SpecShield作为你的Optic替代品：

# No signup needed for the CLI diff command
npx specshield compare old-openapi.yaml new-openapi.yaml

对于仪表盘、历史记录、GitHub应用和BDCT：在specshield.io/signup上免费注册 — 无需信用卡，提供慷慨的免费套餐。价格详情在specshield.io/pricing。

如需迁移支持，请将邮件发送至founder@specshield.io —我很乐意帮助任何Optic难民迁移，免费地，无论你最终是否使用SpecShield。迁移比工具更重要。

这个指南有帮助吗？它是关于Optic API工具集后时代的一系列活动的一部分。下一篇文章：对SpecShield、oasdiff和Optic存档规则集的破坏性变更规则的深度技术比较——包括每个工具捕捉到的边缘情况，而其他工具遗漏的情况。

有反馈或更正？在下面留言或直接邮件给我。我宁愿做得正确，也不愿做得快。