架构与系统设计 / 系统课时

设计 API 的向后兼容演进

设计 API 的向后兼容演进

API 演进的难点不是“把新版本发出去”,而是让旧调用方在尚未升级时仍能继续工作。本篇用兼容字段、弃用周期和版本边界,建立一套可执行的接口变更顺序。

学习目标

  • 判断字段新增、删除、改名和语义变化是否会破坏旧调用方
  • 设计“先扩展、再弃用、后移除”的兼容演进周期
  • 知道什么时候应继续兼容,什么时候应启用新版本

先识别真正的破坏性变更

向后兼容的判断标准是:新服务上线后,按旧契约编写的调用方是否还能得到它能理解的结果。因此,“服务端能处理”不代表“客户端不会坏”。

常见变化可以这样判断:

变化 通常是否兼容 主要风险
响应新增可选字段 是 严格反序列化客户端可能拒绝未知字段
请求新增可选字段 是 服务端必须为缺省情况保留旧行为
删除或改名现有字段 否 旧客户端仍会读取或发送原字段
把可选字段改为必填 否 旧客户端不会提供该字段
扩展枚举值 不一定 穷举式客户端可能遇到未知值
改变字段含义或单位 否 结构没变,但业务语义已经破坏

用扩展式变更跨过多版本并存期

最稳妥的顺序是先让新旧调用方都能工作,再推动调用方迁移,最后删除旧契约。假设原接口返回 name,现在希望拆成 firstName 和 lastName,不要直接把 name 删除。

API 兼容演进时间线

在过渡版本中,服务端同时返回旧字段和新字段,并让两者表达同一个业务事实。以下请求假设本地服务已启动在 <PORT>,将其替换为实际端口后执行,实际值可能不同。

bash
curl -s http://localhost:<PORT>/users/42

预期输出:

json
{
  "id": 42,
  "name": "Ada Lovelace",
  "firstName": "Ada",
  "lastName": "Lovelace"
}

旧客户端继续读取 name,新客户端可以开始使用 firstName 与 lastName。只有当调用方迁移完成并经过一个明确的弃用窗口后,服务端才进入删除旧字段的收缩阶段。

把弃用当成协议而不是注释

弃用周期至少要包含三个信息:从哪个版本开始弃用、替代方案是什么、最早何时移除。如果平台可观测调用方版本,还应先确认旧字段实际使用量已经下降到可接受范围。

对于 HTTP API,可以在文档和响应元数据中同时暴露弃用信息;对于 SDK,还可以在类型或方法上标记 deprecated。关键不是“提醒过”,而是给调用方足够的双栈时间,使发布节奏彼此解耦。

在删除旧字段前,至少检查:

  • 旧字段调用量是否已经降到约定阈值
  • 关键调用方是否完成迁移和回归验证
  • 回滚到上一服务版本时,新旧数据是否仍能互相理解
  • 监控和告警是否已经切换到新字段、新错误码或新事件名

版本策略只处理无法兼容的变化

不要把每次小改动都变成 /v2。如果新增可选字段就能满足需求,继续演进现有版本通常更容易维护。只有当新旧语义无法同时成立时,才值得建立新版本边界。

适合新版本的典型场景包括:字段语义彻底改变、资源模型重构、认证方式不兼容、错误模型重写,或必须删除旧行为才能保证正确性。此时应让旧版本继续服务一段迁移期,而不是在发布新版本当天强制所有调用方切换。

真正可维护的 API 演进依赖的是兼容窗口和退出机制:先扩展契约,再观察迁移,最后收缩;版本号只是当兼容已经无法成立时才使用的边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计 API 的向后兼容演进

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通