接口契约回归 Agent：别等联调炸了，先让 OpenAPI 变更自己说清风险

接口测试里最烦的不是写一个请求，而是判断“这次接口改动到底会不会影响老客户端、老页面、老自动化用例”。字段改名、枚举收紧、响应码变化、鉴权变化、分页结构变化，这些问题如果只靠人工扫 PR，很容易漏。

这篇给的是一个小工具组合，不是大平台：oasdiff 负责找 OpenAPI 契约差异，Schemathesis 负责从 schema 生成接口探测，AI Agent 负责把差异翻译成 QA 能审的测试风险和回归建议。

适合的 QA 工作类型：接口测试、服务端测试、契约测试、PR 变更回归。

AI 直接参与的动作：读取契约差异，转成风险说明、重点回归接口、断言建议和缺陷复现描述。

真实场景：研发说“只改了一个字段”，QA 怎么确认？

接口联调里常见一句话：“这个字段前端不用了，我删掉了。”

但 QA 真正要判断的是：

1. 老版本 APP 是否还会读这个字段。
2. 小程序线上版本是否还依赖这个响应结构。
3. 自动化用例是否只覆盖了成功样例，没有覆盖字段缺失。
4. 错误码、枚举、必填参数、鉴权策略有没有一起变化。
5. 这次变更应该阻断合并、允许灰度，还是只补回归点。

如果完全人工看 OpenAPI diff，字段一多就会变成纯体力活。更好的方式是先让工具把“可能破坏兼容”的地方列出来，再让 AI 转成 QA 语言，最后由 QA 做判断。

工具分工：不要让 AI 做所有事

这类场景最忌讳把所有责任都丢给 LLM。LLM 不应该负责判断 OpenAPI 两个版本到底哪里变了，因为这件事有确定性工具。

更稳的分工是：

1. oasdiff：比较 base/head 两份 OpenAPI，输出 breaking changes 或 changelog。
2. AI Reviewer：读取差异，把它转成 QA 风险：哪些接口、哪些客户端、哪些断言要补。
3. Schemathesis：基于 OpenAPI 自动生成探测请求，覆盖边界参数和异常响应。
4. QA：审查 AI 输出是否符合业务兼容策略，决定阻断、放行还是补例外说明。

官方文档里，oasdiff breaking 的目标就是显示会破坏现有 API client 的变更，changelog 则显示可能影响消费者的非纯文档变化。文档也提到这些命令常用于 CI 来报告或阻止 breaking changes。

Schemathesis 官方说明则更偏执行层：它会从 OpenAPI 或 GraphQL schema 自动生成 property-based tests，去探索可能破坏 API 的边界情况，并给出最小 curl 复现命令。

原始做法 vs Agent 工作流

原始做法通常是：

1. QA 打开接口文档或 PR。
2. 人工对比字段。
3. 选几个熟悉的接口手动请求。
4. 发现问题再写缺陷。
5. 下次类似变更继续重复这一套。

Agent 工作流应该改成：

1. CI 或本地脚本拿到 base/head 两份 OpenAPI。
2. oasdiff breaking 输出结构化差异。
3. AI 把差异翻译成“对 QA 意味着什么”。
4. Schemathesis 对受影响接口跑一轮小范围探测。
5. QA 审查风险摘要和失败复现命令。
6. 通过的探测沉淀为回归点，阻断的变更进入缺陷或兼容评审。

最小验证路径：拿一个接口先跑通

不要一上来把全公司 OpenAPI 都接进来。先选一个接口，比如订单详情、用户配置、会员权益查询。

准备两份文档：

openapi-base.yaml
openapi-head.yaml

先做契约差异：

oasdiff breaking openapi-base.yaml openapi-head.yaml

如果要让 CI 在明确错误级别时失败，可以参考官方文档里的 --fail-on ERR 或 --fail-on WARN 思路。但在团队刚落地时，我不建议直接对所有 WARN 阻断。先让 QA 看一周输出，建立误报和例外规则。

再对目标 API 做一轮 schema 探测：

uvx schemathesis run http://test-env.example.com/openapi.json

这不是为了证明“接口一定没问题”，而是为了快速找到人工样例不容易覆盖的边界输入、状态码不一致、响应不符合 schema、服务端 500 这类问题。

AI 可以接在两个输出后面，让它只做三件事：

1. 把每条 breaking change 转成 QA 风险句子。
2. 给出需要补的正向/反向断言。
3. 把失败输出整理成缺陷复现模板。

不要让 AI 自己决定是否放行。

提效点拆解

第一，少扫字段。

契约差异由确定性工具给出，QA 不再靠肉眼在两份文档里找新增、删除、必填变化、响应结构变化。

第二，少凭经验挑接口。

差异能告诉你哪些 operation 发生了变化，Schema 探测能优先覆盖受影响接口，而不是整套回归平均用力。

第三，少写重复断言。

AI 可以根据差异建议断言：字段是否仍存在、枚举是否兼容、错误码是否符合文档、老参数是否仍被接受。

第四，少写缺陷描述。

Schemathesis 这类工具给出的最小复现命令，加上 AI 整理的影响范围，可以让缺陷单更接近“研发可直接定位”的状态。

QA 必须人工校对什么

第一，breaking change 不等于一定不能发。

如果这是大版本接口、灰度接口、只给新客户端使用，可能允许变更。是否阻断要结合版本策略。

第二，文档变更不等于服务实现变了。

有时是 OpenAPI 补文档，有时是实现先变文档后补。QA 要确认测试环境里的真实行为。

第三，AI 生成的断言不能全收。

有些断言太细，会导致自动化用例和实现强绑定。QA 要保留业务稳定断言，删掉脆弱的内部实现断言。

第四，探测请求要控制数据影响。

对订单、支付、库存、权益类接口，不能随便跑会改变状态的请求。需要只读环境、Mock、沙箱账号或明确清理策略。

更适合落地在哪些接口

优先选这些：

1. OpenAPI 文档相对完整的服务。
2. 历史上经常因为字段兼容出问题的接口。
3. 有多端消费者的接口，例如 APP、小程序、H5、后台都在用。
4. 响应结构复杂、枚举多、分页多、错误码多的接口。
5. 已经有 CI，但接口回归还依赖人工抽查的团队。

暂时不适合这些：

1. 文档长期失真，OpenAPI 和真实接口完全对不上。
2. 接口强依赖复杂状态，无法准备测试数据。
3. 变更策略本来就没有版本兼容要求。
4. 团队没有人愿意维护契约例外规则。

总结

接口契约回归 Agent 的核心不是“让 AI 测接口”，而是把接口变更拆成三层：确定性差异、可执行探测、人工兼容判断。

oasdiff 和 Schemathesis 负责确定性和执行，AI 负责把输出变成 QA 能审的测试风险，QA 负责最终判断。

这条链路的最小价值很清晰：PR 阶段提前暴露破坏性变更，把一次联调事故转成可复用的契约回归资产。

官方资料

• oasdiff Breaking Changes 文档
• Schemathesis 官方文档