API 契约演进要让生产者和消费者跨版本保持可预测

API 演进不是把版本号加一，而是在服务不断变化时维持调用方可以理解的行为。机器可读契约能够描述路径、参数、消息结构和响应，但兼容性还包括状态码、默认值、顺序、延迟、权限和副作用。只有把语法与行为一起管理，版本策略才有实际意义。

契约先描述可观察边界

OpenAPI Specification 为 HTTP API 提供与语言无关的描述方式，可以记录操作、参数、请求体、响应、认证方案和数据模式。它便于生成文档、客户端、模拟服务和校验规则，也能支持变更比较。规范文件应与部署版本绑定，不能长期由人工页面替代真实接口。

契约描述的是允许出现的交互。实现返回契约外字段、遗漏必需字段或改变类型，都可能破坏消费者。反过来，契约写得过宽，例如所有字段都可空、错误响应只有任意对象，也无法提供有效保护。模式应表达真实边界，但不要把暂时实现细节误写成永久承诺。

HTTP 方法和状态码具有协议语义。GET 的安全性、幂等方法的重试含义、缓存控制和条件请求都会影响客户端行为。即使 JSON 结构不变，把不存在资源从 404 改为 200 空对象，也可能改变缓存、告警和业务分支。

响应增加可选字段通常对忽略未知字段的客户端兼容，但严格反序列化器可能失败。请求增加可选字段对旧客户端通常兼容，新服务器仍要正确处理缺省。将可选字段改为必需、收紧枚举、改变格式或删除字段风险更高。

枚举尤其容易被低估。服务器未来增加枚举值时，旧客户端若使用封闭分支会崩溃。契约应说明未知值处理策略，代码生成配置也要验证。字段从整数变字符串，即便视觉内容相同，也属于类型破坏。

语义变化无法完全由模式检测。例如金额单位从元变分、列表默认排序改变、过滤条件由包含改为前缀匹配，schema 都可能不变。变更评审需要列出每项可观察行为、受影响消费者和迁移方法。

版本可以放在路径、请求头或媒体类型中，各有缓存、路由和可见性取舍。关键不是形式，而是同一版本内允许什么变化、旧版本支持多久以及如何发现使用者。每个版本应有所有者、发布日期、弃用日期和流量数据。

新增版本不能自动完成迁移。生产者要提供变更说明、并行期和测试环境，消费者要确认升级。弃用通知应通过文档、响应头、开发者渠道和直接联系共同完成；只在发布日志写一句，无法覆盖长期无人维护的调用方。

长期同时维护过多版本会放大安全补丁和数据一致性成本。应把版本视为迁移窗口，而不是无限分叉。删除前检查真实流量、服务账号、批处理任务和灾备脚本，低频调用也可能承载关键流程。

生产者的契约测试验证实现符合声明，消费者测试验证其实际依赖仍被满足。两者关注点不同。消费者不应把所有偶然字段和顺序都固化成依赖，但必须覆盖关键业务路径、错误响应和重试行为。

变更比较工具可以发现字段增删、类型和必需性变化，无法判断业务语义。自动门禁之后仍要进行人工兼容评审。对高风险操作，应在预发布环境回放脱敏请求或运行代表性消费者。

容错读取不代表无限宽松。忽略未知响应字段通常合理，忽略未知请求字段可能掩盖拼写错误；接受多种日期格式会增加歧义。每个方向的宽容程度要由协议角色和风险决定，并以告警暴露即将废弃的用法。

稳定契约必须包含错误结构。客户端需要区分认证失败、权限拒绝、资源不存在、冲突、限流和服务故障。把所有失败包装成 200 会破坏通用 HTTP 组件，也让重试判断困难。错误码与可读消息应分离，前者保持稳定，后者可改进表述。

超时后客户端可能不知道服务器是否已完成写入。幂等键、条件更新或业务操作标识可以帮助安全重试，但要规定作用域、保留时间和冲突响应。仅因使用 PUT 就假定整个业务过程幂等并不充分，外部通知和异步副作用仍可能重复。

分页契约也需要稳定。偏移分页在数据持续变化时可能重复或遗漏，游标分页需要定义游标有效期与排序。若排序字段不唯一，应加入稳定的次级键。客户端不应解析不透明游标内部结构。

网关可以记录版本、消费者、状态码和延迟，帮助识别迁移风险。日志要避免保存令牌和敏感正文。指标应区分协议错误、业务拒绝和服务故障，不能用一个总体成功率掩盖某版本退化。

发布时可先让新旧实现并行，使用影子流量或小比例消费者验证。涉及写操作时，影子请求不能产生真实副作用。回滚不仅要恢复代码，还要考虑新版本已经写入的数据是否仍能被旧版本读取。

API 契约的目标是让独立演进的团队拥有共同、可测试的边界。规范文件是基础，兼容政策、消费者证据、运行观测和清晰弃用共同决定这条边界是否可信。