Codex CLI 增量迭代实战：3 步实现跨版本 API 兼容性自动校验

1. 跨版本 API 兼容性校验，为什么不能靠人眼比对？

上周三下午，我们团队在发布 v2.3.0 版本前做最后一次回归验证，发现一个接口的响应字段user_profile突然从对象结构变成了字符串。它没报错，但下游三个服务全崩了——因为它们都硬编码了.profile.avatar_url的取值路径。这个 bug 没进测试用例，也没触发任何 CI 报警。人工走查时，我盯着 Postman 里两版 Swagger 文档对比了 17 分钟，还是漏掉了这个字段类型变更。

这不是个例。过去三个月，我们累计在 5 个微服务间发现了 12 处隐性不兼容：字段名拼写微调（user_id→userId）、枚举值新增未加@Deprecated、嵌套层级被扁平化、甚至某个GET /users接口悄悄把分页参数从page_num改成了pageNumber——文档更新了，但旧客户端根本没收到通知。

传统方案在这里彻底失效：Swagger Diff 工具只能比对 OpenAPI YAML 的文本差异，无法识别语义等价（比如integer和int32实际等效）；Postman Collection Runner 只能跑预设请求，没法自动推导出“哪些字段被删/改/重命名”；而让工程师手动维护一份《兼容性变更清单》？上线前临时补的文档，90% 都是错的。

Codex CLI 不是另一个代码生成器。它是第一个能把「API 向后兼容性」这个模糊概念