API 不断发展。新功能、更正、弃用。但客户端依赖于当前的接口。版本控制允许在不破坏现有应用程序的情况下进行演进。本指南介绍了策略和最佳实践。
为什么版本
兼容性
老客户继续营业。
进化
改进而不阻塞。
文档
明确预期会发生什么。
过渡
客户迁移的时间。
何时版本
重大变化
破坏契约的变更。
示例
- 删除字段
- 更改数据类型
- 改变含义
- 删除端点
不要版本为
添加，通常是兼容的。
版本控制策略
URL路径
/api/v1/用户，/api/v2/用户。
查询参数
/api/用户？版本=1。
标题
0或1。
内容协商
2。
URL 路径版本控制
优势
可见、清晰、易于路线。
缺点
URL 随版本而变化。
示例
获取 /api/v1/产品 获取 /api/v2/产品
常见
最流行的方法。
标头版本控制
优势
干净、语义正确的 URL。
缺点
不太明显，更难测试。
示例
获取/api/产品 标头：API 版本：2
语义版本控制
格式
主要.次要.补丁。
专业
重大变化。
次要
兼容的添加。
补丁
很酷的虫子。
对于 API
一般只有公共版本中的MAJOR。
弃用
流程
删除之前标记为已弃用。
通讯
标题、文档、变更日志。
时间轴
迁移截止日期。
支持
保留多久不推荐使用。
日落标题
HTTP 标头
3。
弃用标头
表明它已被弃用。
通讯
客户端可以自动检测。
迁移
文档
发生了什么变化，如何适应。
指南
一步步迁移。
支持
过渡期间的帮助。
时间轴
合理的期限。
向后兼容性
目标
新客户端、旧 API 都可以工作。
添加剂
添加，不要删除。
默认值
具有默认值的新字段。
###可选
新的可选参数。
向前兼容性
概念
老客户使用新 API。
忽略未知
忽略未知字段。
优雅的降级
无需新功能即可工作。
进化设计
可扩展性
想想未来的变化。
通用结构
可扩展的对象。
功能标志
不要暴露不完整的功能。
合约
清楚地定义你的承诺。
多个版本
维护
维护几个的费用。
限制
同时支持多少个。
政治
制定明确的规则。
文档
按版本
特定于版本的文档。
变更日志
版本之间发生了什么变化。
迁移指南
如何更新。
弃用通知
会出来什么。
工具
OpenAPI/Swagger
版本规范。
邮递员
按版本收集。
API 网关
版本路由。
常见错误
版本太多
每次更改都有新版本。
不要版本
没有新版本的重大更改。
快速弃用
不允许有时间进行迁移。
没有沟通
客户对变化感到惊讶。
SDK 和客户端
对应版本
API v1 的 SDK v1。
维护
保持 SDK 更新。
通讯
通知新版本。
结论
API 版本控制是一项长期的学科。选择明确的策略，传达变更并留出迁移时间。其结果是 API 能够在不破坏集成的情况下不断发展。
##常见问题解答
1) 使用哪种版本控制策略？ URL 路径是最常见的，建议大多数人使用。
2) 何时增加主要版本？ 用于不向后兼容的重大更改。
3) 旧版本支持多长时间？ 6-12个月是常见的。这取决于客户。
4) 我可以在不进行版本控制的情况下进行更改吗？ 添加一般是的。没有删除/更改。
5) 如何报告弃用？ 标题、文档、电子邮件、过渡期。
另请阅读
- [GraphQL 应用程序：实施指南4
- [应用后端：架构、技术和最佳实践5
- [应用中的微服务：移动分布式架构6
- [应用程序API7
- [应用API - 日常生活中的一步一步8
- [应用程序API - 逐步扩展9