技能使用指南

api-contract-diff（OpenAPI契约差异评审）Skill 是什么？如何下载？

api-contract-diff 技能可对比两版 OpenAPI 文档，把字段差异分为破坏性、行为性、兼容三级，给出消费方影响面、迁移示例与灰度下线计划，并附可运行差异脚本。本文详解其安装思路、使用步骤、竞品对比与典型场景，助你在发版前拦住 breaking change。

OpenAPI契约差异评审Skillapi-contract-diff
19 个章节 约 16 分钟阅读 AI 智能生成

OpenAPI契约差异评审Skill：三分钟判断两版接口改动会不会打断调用方

  • 它解决的是“改完之后敢不敢发”的问题：把两版 OpenAPI 文档的字段级差异，自动归类为破坏性、行为性、兼容三级，并给出对应的发布策略。
  • 输出不止是差异清单：除了“改了哪些字段”，还会给出消费方影响面、迁移示例、下线计划，可直接整理成给客户看的变更公告。
  • 自带可运行脚本：scripts/diff_openapi.py 支持以 Markdown 格式输出差异结果，评审结论有据可查，不靠肉眼比对文档。
  • 最擅长抓“隐性破坏”：枚举收窄、校验收紧、新增必填字段、响应字段删除这类“看起来没事、上线就出事”的改动，是它的重点检查项。
  • 适用边界清晰：面向 REST/HTTP API 的版本升级、微服务契约治理与对外接口评审；GraphQL schema 差异与纯性能优化场景不适用。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能中文名：OpenAPI契约差异评审Skill 技能英文名：api-contract-diff 技能ID：2119807731773374465

这个技能要解决的问题非常具体：当服务端准备发版、要对外发布 API 变更公告、或者多个团队共用同一个网关时，谁来判断“这次改动到底会不会打断调用方”？现实中常见的做法是拉一个会议，几个人对着两份 YAML 人工比对，最后凭感觉拍板。结果往往是上线第二天收到客户工单：某个字段没了、某个枚举值不认了、某个请求突然报 400。

api-contract-diff 把这件事流程化：输入旧版与新版 OpenAPI 文档，输出“改了什么、会不会打断调用方、该怎么发布”三个答案。

一键安装的思路与步骤

AI 技能的“一键安装”，本质是把技能包（包含提示词工作流、参考文件、可执行脚本）挂载到你所使用的 AI 助手中，之后每次对话都能直接调用这套能力。具体步骤如下：

  1. 确认安装前提
    • 你使用的 AI 助手/智能体平台支持技能（Skill）机制，并能访问其技能市场或技能库；
    • 你手上能拿到两版 OpenAPI 文档（JSON 或 YAML 格式）；
    • 因为技能内置了 scripts/diff_openapi.py 脚本，建议运行环境具备 Python 执行能力与文件读写权限，否则只能使用“分析推理”部分的能力，无法直接跑脚本。
  2. 执行安装
    • 在技能市场/技能库中按技能名 api-contract-diff 或技能ID 2119807731773374465 检索并安装/启用；
    • 具体的安装命令、入口位置、是否支持本地部署等，以官方说明为准（本技能详情未提供安装命令与链接，请勿凭猜测执行）。
  3. 验证是否生效
    • 在对话中直接提问：“用 api-contract-diff 比较这两个版本的 OpenAPI 文档”，观察助手是否会按“字段级提取 → 三级分类 → 消费方影响面 → 发布策略 → 验证”的工作流回应；
    • 检查技能包内的 references/breaking-changes.md、references/versioning-policy.md、scripts/diff_openapi.py 是否可正常读取；
    • 用一个已知包含破坏性改动的小样例（例如新版把某个请求字段从可选改成必填）试跑一次，看是否被正确判定为“破坏性”。

如果平台侧暂不支持技能机制，也可以把技能详情中的工作流与检查清单作为评审规范，人工按步骤执行——这套方法论本身就能当团队内部的 API 变更评审 SOP 用。

该技能的主要功能和特点

  • 字段级归一化提取：把两份文档拍平成统一可比结构 {path} {method} -> params / requestBody / responses / security / deprecated，只比较真正暴露给调用方的契约，自动忽略描述文案、示例值、tag 顺序等非语义噪音，避免“文档改了个错别字”被误报成变更。
  • 三级变更分类：破坏性（删除/重命名路径或必填字段、收窄枚举、收紧校验、改变类型、新增必填请求字段、移除响应字段、改变状态码语义）、行为性（放宽校验、新增可选字段、新增响应字段、默认值变化、分页上限调整）、兼容（新增路径、新增可选参数、文档修正）。分级直接对应处理动作，不用再二次讨论。
  • 消费方影响面标注：对每条破坏性变更标注受影响消费方、最坏后果（编译失败 / 反序列化失败 / 静默取默认值 / 业务错误）和探测方式（SDK 重新生成、契约测试、网关采样）。尤其把“静默取默认值”列为最高优先级——因为它不报错，却会算错数。
  • 四种发布策略可选：追加式演进、双版本并行（/v1 与 /v2 共存，网关按 Header 或路径路由）、兼容层映射（旧新字段双向转换 + 下线日期）、强制升级（仅限内部且消费方可控）。
  • 附带可运行差异脚本：python scripts/diff_openapi.py old.json new.json --format markdown，直接把差异结果输出为可贴进评审单的表格。
  • 检查清单防漏：把“枚举收窄与校验收紧”这类最容易漏判的项单独列为必查项，并要求每条破坏性变更都配消费方与迁移方式、旧版本下线日期与监控指标。
  • 标准输出模板：结论、破坏性变更表、行为性变更表、迁移指南（旧请求 → 新请求）、下线计划（冻结日期/下线日期/监控指标），直接可交付。
  • 反模式库：明确指出“只是加了个字段一定兼容”“用 HTTP 200 返回错误体来避免破坏”“只靠人工比对不做契约测试”等常见踩坑方式。

和普通文本比对工具相比，它强在判断力：普通 diff 工具只告诉你“这里有差异”，它告诉你“这个差异会不会让某个 SDK 反序列化失败、要不要开双版本、什么时候能下线”。

如何使用该技能？

第 1 步：准备输入

至少准备两项，最好四项齐全：

  1. 旧版与新版 OpenAPI 文档（JSON 或 YAML）；
  2. 接口消费方清单（内部服务、SDK、第三方客户）；
  3. 版本策略：URL 版本、Header 版本还是仅追加式演进；
  4. 是否允许一次性强制升级。

提示：如果暂时拿不到消费方清单，技能会按“全部视为外部调用方”从严处理，结论会偏保守，适合早期评审。

第 2 步：发起评审

在对话中把两份文档（或文件路径）交给技能，并明确你的诉求，例如：

  • “帮我比较 old.yaml 和 new.yaml，判断有没有破坏性变更。”
  • “这是本次发版的 OpenAPI，需要给客户写一份变更公告。”

第 3 步：运行脚本做机器比对

python scripts/diff_openapi.py old.json new.json --format markdown

脚本输出的 Markdown 表格可以直接作为评审单的附件，也可作为 AI 结论的交叉校验。

第 4 步：阅读三级分类结果

以一次典型改动为例——旧版 status 字段枚举为 [active, inactive]，新版收窄为 [active]；同时新增了一个必填请求字段 tenant_id：

  • status 枚举收窄 → 破坏性（调用方仍在传 inactive 会被拒）；
  • 新增必填请求字段 tenant_id → 破坏性（旧请求直接 400）；
  • 若同时新增了一个可选响应字段 created_by → 行为性（需公告，可同版本发布）。

这一步最容易犯的错，是只看到“响应变多了”就判定为兼容，而忽略了请求侧的收紧。

第 5 步：按模板产出结论与迁移指南

技能会按固定模板输出：

  • 结论：例如“本次变更包含 N 项破坏性变更，建议采用「双版本并行」发布”；
  • 破坏性变更表：位置 / 变更 / 影响 / 消费方 / 处理；
  • 行为性变更表：位置 / 变更 / 注意事项；
  • 迁移指南：旧请求 → 新请求的对比示例（可直接复制进公告）；
  • 下线计划：版本 / 冻结日期 / 下线日期 / 监控指标。

第 6 步：补契约测试并验证

对每条破坏性变更补一条契约测试，验证原则是：旧请求打到新服务上，必须得到明确错误，而不是静默成功。这也是技能反复强调的反模式——用 HTTP 200 返回错误体来“避免破坏”，只会让监控和重试逻辑集体失效。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
api-contract-diff（本技能） 面向“发版决策”的契约差异评审助手 字段级提取、三级分类、消费方影响面、发布策略、检查清单、差异脚本、变更公告模板 需在支持技能机制的平台安装，脚本运行需 Python；具体入口以官方说明为准 版本升级评审、对外 API 公告、微服务契约治理 优势：不止列差异，还给发布策略与迁移文案，覆盖“隐性破坏”；不足：依赖 OpenAPI 文档质量，GraphQL 与纯性能优化场景不适用
oasdiff 等开源 OpenAPI 差异 CLI 命令行差异检测工具 输出两版规范的结构化差异，可配置破坏性规则、可接入 CI 需自行安装与配置规则，学习成本中等 CI 门禁、批量扫描 优势：可自动化、可集成流水线；不足：只给差异与规则命中，不产出消费方影响分析、迁移指南与下线计划
契约测试框架（如 Pact 类工具） 以测试保障契约一致性 消费方驱动契约、提供方验证、测试报告 需搭建 Broker、编写测试用例，落地成本较高 已具备成熟测试体系的团队 优势：能验证真实行为，防回归能力强；不足：偏事后验证，事前“该不该这么改”的判断仍需人工，且需要消费方配合编写用例
API 网关/API 管理平台的契约治理模块 平台化的接口资产管理 规范托管、变更记录、审批流、灰度路由 通常需采购或接入统一平台，接入周期长 大型组织统一治理 优势：流程闭环、有审批与审计；不足：重、启动慢，个体团队临时评审用不上，细粒度字段级兼容判定未必覆盖
人工比对文档 + 会议评审 传统做法 肉眼查看、口头讨论 零门槛 小改动、紧急场景 优势：灵活；不足：极易漏判枚举收窄与校验收紧，结论无法沉淀，无法复核

选择建议：如果你需要的是**“这次能不能发、怎么发、怎么通知客户”，本技能更贴题；如果你需要的是流水线里每次提交自动拦一道**，可以把开源差异 CLI 与本技能组合使用——CLI 做门禁，技能做决策与文案。

该技能的典型应用场景与实际体验情况

场景一：后端服务发版前的破坏性变更评审

角色：后端研发 / 技术负责人。 痛点：需求方说“只是加个字段”，但实际改动里悄悄把某个字段从可选改成了必填，上线后老客户端整片报 400。 使用方式：发版前把两版 OpenAPI 丢给技能，重点看“新增必填请求字段”“响应字段删除或类型变化”两类判定结果，再对照检查清单逐条打勾。 实际体验：上手几乎零成本，只要文档规范齐全，几分钟就能出结论；效果最明显的是把“感觉没问题”变成“有清单可核对”。注意事项是——文档本身若滞后于代码，结论会失真，评审前务必确认 OpenAPI 是随代码生成的。

场景二：对外 API 的客户可读变更公告

角色：开放平台运营 / 客户成功 / 解决方案工程师。 痛点：技术同学给的变更说明全是术语，客户看不懂；业务同学自己写又容易漏项。 使用方式：用技能输出的“迁移指南”模块，直接拿到旧请求 → 新请求的对比示例，再补上时间节点即可成稿。 实际体验：迁移示例可直接复制，公告撰写时间从半天压缩到半小时级。注意事项：客户侧的 SDK 版本兼容情况仍需人工确认，技能只能基于你提供的消费方清单来判断。

场景三：单体拆分微服务时的语义对齐

角色：架构师 / 网关团队。 痛点：拆分后新旧接口语义漂移，比如同一个字段在旧服务里必填、新服务里可选，调用方按旧语义写代码就会踩坑。 使用方式：把拆分前后的接口契约分别导出为 OpenAPI，用技能做字段级比对，重点看类型变化、默认值变化、状态码语义变化。 实际体验：默认值变化 这类被归为“行为性”的改动往往被低估——它能同版本发布，但需要公告。技能把它单独列出来提醒，这一点很实用。注意事项：拆分场景下路径可能整体变化，需要先做路径映射再做比对，否则会产生大量“删除+新增”的噪音。

场景四：多团队共用网关的契约门禁

角色：平台工程 / SDK 维护者。 痛点：十几个团队往同一个网关上发接口，没有统一规则，SDK 每次重新生成都可能编译失败。 使用方式：把 scripts/diff_openapi.py 接入 CI，命中破坏性规则时阻断合并；同时用技能的检查清单沉淀成团队评审规范。 实际体验：脚本输出的是 Markdown 表格，贴进 PR 评论即可，评审留痕清晰。注意事项：门禁规则初期误报会比较多，建议先以“只告警不阻断”跑一到两周，把团队自己的例外情况（比如内部专用接口允许强制升级）写进策略里。

该技能能为用户带来的价值

  • 把“发版焦虑”变成“发版流程”：以往靠经验判断兼容性，现在有一份固定工作流与检查清单，结论可复核、可沉淀，新人也能按图索骥。
  • 显著降低线上事故概率：破坏性变更漏判的代价通常是一次客户故障 + 一轮紧急回滚。技能把“枚举收窄、校验收紧、新增必填字段”这几个高频漏判点设成必查项，把风险拦在发布之前。
  • 节省跨团队沟通成本：一份包含结论、影响面、迁移示例、下线计划的输出，可以直接作为研发、产品、客户成功三方共用的沟通底稿，减少“再开个会对一下”的往返。
  • 让 API 演进有长期纪律：双版本并行、兼容层映射、下线日期与监控指标——这些动作写进模板后，团队会自然形成“先定下线计划再改接口”的习惯，长期看能显著减轻历史包袱。
  • 降低工具门槛：不需要自己搭一套契约治理平台，也不需要写比对脚本，装好技能、给出两份文档，就能拿到接近专家评审的结论。

常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？ A：在支持技能机制的平台中按技能名 api-contract-diff 或技能ID检索并启用即可；若平台支持一键安装，按提示操作。是否需要付费、是否支持本地部署、具体安装命令与入口，以官方说明为准——本技能详情未提供价格与安装命令，请勿依据第三方猜测操作。

Q2：我的接口文档不是 OpenAPI 格式，能用吗？ A：技能明确面向 OpenAPI（JSON 或 YAML）文档，适用于 REST/HTTP API。GraphQL schema 差异不适用（技能中提到可参考同一套三级分类思路自行处理）；纯性能优化且契约未变的场景也不需要它。如果是 Postman、Apifox 之类的集合，建议先导出为 OpenAPI 再做比对。

Q3：它和开源的 OpenAPI diff 工具有什么区别？ A：开源 diff 工具回答的是“哪里不一样”，本技能回答的是“会不会打断调用方、该怎么发布、公告怎么写”。前者适合塞进 CI 做门禁，后者适合发版前的决策会与对外沟通。两者并不冲突，组合使用效果最好：CLI 拦一道，技能出结论与文案。

Q4：拿不到消费方清单怎么办？ A：技能内置了兜底策略——缺少消费方清单时，按“全部视为外部调用方”从严处理。这样结论会偏保守（很多内部接口也会被要求走兼容期），但能避免漏掉长尾调用方。建议后续通过网关访问日志补全清单，把判定精度提上来。

Q5：适合谁用？我一个小团队有必要吗？ A：后端研发、技术负责人、架构师、开放平台/客户成功、平台工程与 SDK 维护者都用得上。团队越小越值得用——小团队通常没有专职的 API 治理角色，一旦破坏性变更漏判，往往就是“客户直接打电话过来”的场面。哪怕只是把它的检查清单打印出来当发版前自查表，也能挡掉大部分低级失误。