审查AI修改的OpenAPI,先检查契约兼容
文章建议审查Cursor修改的OpenAPI时,优先检查路径和字段删除、约束收紧及安全方案变化,评估对客户端等消费者的影响。YAML校验通过不能证明契约正确,合并前还需与服务真实响应核对。
AI 深度解读
Cursor 改了 OpenAPI 文件,PR 里看着只有几行,影响却可能越过当前仓库,落到前端请求、生成的 SDK 和其他团队身上。原文的核心判断是:审查接口描述时,要按契约变更评估,先看会不会破坏调用方,再看它是否符合服务的实际行为。
这篇没有性能实验,也没有工具对照数据,但给出了一套实用的审查顺序。对日常用 AI 改接口、补文档的开发者,最有价值的提醒是:YAML 校验通过,离接口可以安全合并还有一段距离。
两行修改为什么可能影响所有调用方
OpenAPI 是服务和调用方共享的接口契约。生成客户端、Mock、文档、网关,以及依赖接口的团队,都可能读取它。服务仓库自己编译成功,不能证明仓库外的消费者仍然正常。
因此,审查优先级应该由影响范围决定。一个必填字段的 2 行修改,可能比 100 行描述调整更重要;大面积格式化,也可能掩盖真正改变行为的那个操作。
作者建议优先检查路径或字段的删除、重命名,约束是否收紧,以及安全方案是否变化。这些变化不能只看文字是否合理,还要问旧调用方式能否继续工作。
例如,给请求体新增必填字段,旧客户端没有发送它,就可能请求失败。作者建议先设为可选,再在后续版本改为必填。响应侧也可能影响校验,但原文没有展开具体条件,不能把所有响应字段变更都判为同等风险。
审查接口契约,先问旧客户端还能不能用。
删除前,还要搜索更广的代码库、已知客户端仓库,并检查网关日志中的真实流量。当前仓库搜不到引用,不代表外部没人使用。
原文提出的迁移办法是:一个版本先标记废弃,下一个版本再移除,同时写入 API 版本历史,让调用方有机会提前调整。
结构化差异和真实请求要各查一遍
直接看 YAML 的文本差异,容易被缩进、锚点和键顺序干扰。作者建议用结构化差异工具,解析新旧 OpenAPI,比较解析后的接口操作,避免把字段移动误判成删除。
实际审查可以分两步:先对照新旧版本渲染出来的接口定义,再沿着变更路径找到处理请求的代码。
这里最容易出问题的是「文档和代码不一致」。Cursor 可以迅速把文档改成代码当前的样子,但团队得先判断哪一边才是正确行为。如果服务实现违反了已经承诺的契约,直接改文档,只是让差异从 PR 里消失,客户端仍会遇到问题。
作者因此建议保护 OpenAPI 文件,并要求第二人复核。自动检测可以辅助识别破坏性变更,但有些变化涉及业务含义,未必能从结构上判断出来。
接下来还要验证运行中的服务。修改 spec 不会部署后端,也不会自动改变接口行为。结构合法的文档,完全可能描述了服务没有实现的状态码或字段。
原文以 Powerduck 为例:导入更新后的 spec,通过本地主进程运行有顺序的场景断言,检查真实服务返回的状态码和响应字段。其中的 AI 审查用于提示疑点,不能证明契约正确。
结构检查回答文档怎么变了,真实请求验证服务是否兑现了这些变化。
我的判断
作者把契约兼容性放在文件合法性之前,这个顺序合理,尤其适合前后端分仓、自动生成客户端,以及多个团队共享 API 的项目。只检查服务端仓库,很容易遗漏真正承受变更成本的调用方。
但原文没有提供实测结果,也没有比较 Powerduck 与现有测试方案的效果。工具部分只能作为一种工作流示例,不能据此认定它比团队已有的接口测试或契约测试更可靠。关键是能否执行相关场景、检查关键断言。
「一个版本废弃、下一个版本删除」也只是迁移建议。版本发布得多快、调用方升级得多慢,原文没说清。如果客户端仍在使用旧接口,仅仅跨过一个版本,并不足以支持删除。
真实请求验证同样有覆盖范围:某个场景通过,只能证明这次请求及其断言符合预期。权限、异常路径或字段组合没有测到,就仍有不确定性。它应该和结构化差异审查配合使用。
能拿来做什么
- 让 Cursor 修改接口相关代码时,同时审查 OpenAPI 的路径、字段必填性、约束和安全方案;把删除、重命名等变化放到 PR 审查前面。
- 前端依赖生成客户端或 Mock 时,检查新契约对现有调用代码的影响,并搜索已知调用仓库;不要只凭 Node 服务编译成功判断兼容性。
- 遇到文档与实现不一致,先写清预期契约,再决定修服务还是修 spec,并让第二人复核契约修改。
- 合并前按变更后的契约请求实际服务,断言状态码和关键响应字段;涉及删除时,再结合调用引用、网关流量和迁移安排作决定。