API 字段改名是最危险的破坏性变更，CI 里 diff 规格才能兜住

Franc0Fernand0 · x · 2026-09-25

Franco Fernando 在 Polymathic Engineer 第 192 期继续 API 设计系列，核心观点：已发布的 API 是运行中的服务而非库，一次字段重命名就会让所有解析旧字段名的客户端在部署时挂掉，而这类改动在 code review 里往往被当成无害细节放过。

解法是把 API 布局写成 OpenAPI 规格文件，作为机器可读的单一事实来源，并在 CI 中对规格做 diff，出现破坏性变更就 fail the build。围绕规格还可以：从 spec 生成代码、用真实流量做校验、提供示例与 mock、做好版本管理。作者观点是「意外的重命名应该让构建失败，而不是让集成失败」。