给移动端和合作方的 API 怎么演进:版本、兼容与下线

直接回答: 网页可以随时更新,已经装在用户手机上的 App 和合作方的系统不行,所以 API 一旦发布,就要按“对方可能很久都不升级”来对待。我们的规则是:兼容的改动留在原版本里做,不兼容的开新版本;旧版本先标记弃用,按调用方统计用量,确认用量允许了再下线;接口契约写成文件,在 CI 里检查。

API 版本生命周期图。/v1 先处于在用状态,只做兼容改动;出现不兼容改动时开出 /v2;/v1 随后标记弃用并返回 Deprecation 和 Sunset 头,最后下线并返回明确错误。下方两块:/v1 按 App 版本和合作方密钥统计用量,用量允许时才下线;契约文件在 CI 中与上一版比对,新版本之外的不兼容改动直接失败。
图 1 一个大版本从在用、弃用到下线的过程。下线的依据是用量,不是日历。

1.0 什么算兼容

改动是否兼容
新增可选请求字段、新增响应字段兼容,前提是客户端忽略不认识的字段
新增接口兼容
删除或重命名字段、改字段类型不兼容
可选字段改成必填不兼容
枚举加新值取决于客户端怎么处理未知值,按不兼容来评估更稳妥
改错误码、改默认排序常被当成兼容,实际会打破依赖它们的客户端

最后两行是事故高发区。我们从第一版起就在客户端规范里写明:遇到不认识的枚举值要有兜底显示,不能崩溃。

2.0 版本号放在哪

放在 URL 路径里(/v1/)最直观,日志、网关路由和缓存都好处理,我们默认这么做。放在请求头里看起来更干净,但排查问题时容易漏看。不管放在哪,版本号只在出现不兼容改动时才加,不跟着产品版本号走。

同一个大版本内,服务端偶尔需要按客户端版本做细小的行为差异。让客户端在请求头里带上应用版本号,服务端据此判断,而不是开一堆小版本。

3.0 契约写成文件

接口用 OpenAPI 这类描述文件定义,放在仓库里。CI 做两件事:把本次改动和上一个发布版本的契约做比对,发现不兼容改动又不在新版本里,就让构建失败;用契约测试验证实现和描述一致。

对合作方的接口,契约文件就是开发手册的来源,不再另外维护一份文档。两份东西分开写,迟早对不上。

4.0 弃用与下线

  1. 发布新版本时,旧版本的响应加上 Deprecation 和 Sunset 头(RFC 9745、RFC 8594),文档里写明下线日期。
  2. 按调用方统计旧版本用量:哪些 App 版本、哪些合作方密钥还在调。
  3. 移动端配合最低支持版本:服务端下发最低版本号,低于它的 App 提示升级。
  4. 用量降到可以接受的程度再下线。下线后先返回明确的错误码和升级说明,而不是一个没头没尾的 404。

下线日期要考虑应用商店审核和用户升级的节奏;对合作方,要给他们留出自己开发、测试和发布的时间。

5.0 幂等与重试

移动网络下重试是常态。创建类接口支持幂等键:客户端为每次操作生成一个键,服务端在一段时间内对同一个键返回同一个结果。“提交了两次订单”这类问题,在协议层就挡住了。

给 App 或合作方设计接口,或者整理一套已经失控的接口,见 Web、云端与设备管理。也可以直接聊聊项目。

参考资料

常见问题

只给自家网页前端用的接口,也要这么严格吗?

和后端一起发布、一起回滚的网页前端,可以宽松些,契约检查照样跑就行。只要有一个客户端不能和服务端同步发布,比如 App、小程序或外部系统,就按本文的规则来。

用 GraphQL 是不是就不用管版本了?

GraphQL 的习惯是不分版本,靠新增字段和标记弃用来演进,本质上是同一套兼容规则。删除字段之前,同样要先统计谁还在查询它。

旧版本要维护多久?

没有通用答案,取决于用户升级的速度和合作方的发布周期。我们按实际用量决定,并在发布新版本时就公布下线日期,让对方能排进计划。

内部重构了,对外接口要跟着改吗?

接口描述的是对外承诺,不必跟着内部结构变。内部重构时在服务端做映射、保持外部契约不变,通常是最便宜的做法。