给移动端和合作方的 API 怎么演进:版本、兼容与下线
直接回答: 网页可以随时更新,已经装在用户手机上的 App 和合作方的系统不行,所以 API 一旦发布,就要按“对方可能很久都不升级”来对待。我们的规则是:兼容的改动留在原版本里做,不兼容的开新版本;旧版本先标记弃用,按调用方统计用量,确认用量允许了再下线;接口契约写成文件,在 CI 里检查。
1.0 什么算兼容
| 改动 | 是否兼容 |
|---|---|
| 新增可选请求字段、新增响应字段 | 兼容,前提是客户端忽略不认识的字段 |
| 新增接口 | 兼容 |
| 删除或重命名字段、改字段类型 | 不兼容 |
| 可选字段改成必填 | 不兼容 |
| 枚举加新值 | 取决于客户端怎么处理未知值,按不兼容来评估更稳妥 |
| 改错误码、改默认排序 | 常被当成兼容,实际会打破依赖它们的客户端 |
最后两行是事故高发区。我们从第一版起就在客户端规范里写明:遇到不认识的枚举值要有兜底显示,不能崩溃。
2.0 版本号放在哪
放在 URL 路径里(/v1/)最直观,日志、网关路由和缓存都好处理,我们默认这么做。放在请求头里看起来更干净,但排查问题时容易漏看。不管放在哪,版本号只在出现不兼容改动时才加,不跟着产品版本号走。
同一个大版本内,服务端偶尔需要按客户端版本做细小的行为差异。让客户端在请求头里带上应用版本号,服务端据此判断,而不是开一堆小版本。
3.0 契约写成文件
接口用 OpenAPI 这类描述文件定义,放在仓库里。CI 做两件事:把本次改动和上一个发布版本的契约做比对,发现不兼容改动又不在新版本里,就让构建失败;用契约测试验证实现和描述一致。
对合作方的接口,契约文件就是开发手册的来源,不再另外维护一份文档。两份东西分开写,迟早对不上。
4.0 弃用与下线
- 发布新版本时,旧版本的响应加上 Deprecation 和 Sunset 头(RFC 9745、RFC 8594),文档里写明下线日期。
- 按调用方统计旧版本用量:哪些 App 版本、哪些合作方密钥还在调。
- 移动端配合最低支持版本:服务端下发最低版本号,低于它的 App 提示升级。
- 用量降到可以接受的程度再下线。下线后先返回明确的错误码和升级说明,而不是一个没头没尾的 404。
下线日期要考虑应用商店审核和用户升级的节奏;对合作方,要给他们留出自己开发、测试和发布的时间。
5.0 幂等与重试
移动网络下重试是常态。创建类接口支持幂等键:客户端为每次操作生成一个键,服务端在一段时间内对同一个键返回同一个结果。“提交了两次订单”这类问题,在协议层就挡住了。
给 App 或合作方设计接口,或者整理一套已经失控的接口,见 Web、云端与设备管理。也可以直接聊聊项目。
参考资料
- RFC 9745,The Deprecation HTTP Response Header Field:https://www.rfc-editor.org/rfc/rfc9745
- RFC 8594,The Sunset HTTP Header Field:https://www.rfc-editor.org/rfc/rfc8594
- OpenAPI 规范:https://spec.openapis.org/oas/latest.html
常见问题
只给自家网页前端用的接口,也要这么严格吗?
和后端一起发布、一起回滚的网页前端,可以宽松些,契约检查照样跑就行。只要有一个客户端不能和服务端同步发布,比如 App、小程序或外部系统,就按本文的规则来。
用 GraphQL 是不是就不用管版本了?
GraphQL 的习惯是不分版本,靠新增字段和标记弃用来演进,本质上是同一套兼容规则。删除字段之前,同样要先统计谁还在查询它。
旧版本要维护多久?
没有通用答案,取决于用户升级的速度和合作方的发布周期。我们按实际用量决定,并在发布新版本时就公布下线日期,让对方能排进计划。
内部重构了,对外接口要跟着改吗?
接口描述的是对外承诺,不必跟着内部结构变。内部重构时在服务端做映射、保持外部契约不变,通常是最便宜的做法。