API多版本控制

现状

移动互联网时代，面对市场变化，产品必须不停迭代，而在升级中我们业务需求可能不断在更新，但是我们势必又要保证原来功能的可用性，不能因为用户不升级而导致旧版本无法使用，只能引导用户去更新，而不是强制用户升级。所以我们需要对产品多版本做兼容，解决的核心方向在于服务端API的多版本管理。

存在的问题

• 每个API如何进行灵活的版本管理，多个版本的共存问题
• API多个版本共存维护成本越来越高
• API更新时需要兼容之前的版本，导致参数会越来越多
• API更新后会有很多关于版本的逻辑判断

常见的API版本管理方式

API版本控制主要有下面几种方式。

The Knot: 不设定版本

每个API只有一个版本，所有的用户都必须使用最新的API。
如果直接在原有API上修改，这就意味着所有的用户都必须使用新的版本，需要强制用户更新最新版本的APP，非常影响用户的体验。并且这也会与业务冲突，很多场景业务就有需要新老系统并行的要求。

可选的执行方案：

• 新的API名称
  新功能使用新的API名字，新版本调用新名称API，例如：

https://api.example.com/foo/bar
https://api.example.com/foo/newbar

但是随着版本迭代的次数越来越多，API接口数量也会越来越多，项目冗余代码日益增多，代码变得难以维护。

Point-to-Point: API自带版本

每个API可以有多个不同的版本，API调用方可以根据自己的需要调用不同版本的API。多个版本的API可以共存，老版本的用户不会受到新版本更新的影响。
这种方式只有在系统比较稳定的时候，产品初期版本更新迭代比较快则不太适合，而且如果是每个版本都单独部署的话维护比较麻烦也比较浪费资源。

可选执行方案：

• URI中路径添加版本号

https://api.example.com/v1/foo/bar
https://api.example.com/v2/foo/bar

• URI参数添加版本号

https://www.example.com/api/foo/bar?version=v1

• 使用子域名

https://v1.api.example.com/foo/bar
https://v2.api.example.com/foo/bar

Compatible Versioning: 兼容性版本控制

每个API只提供一个版本，所有用户都调用同一个API，如果要修改API需要兼容旧版本的所有功能。

可选的执行方案：

• 在请求头中添加版本号

GET /foo/bar HTTP/1.1
Host: api.example.com
Accept-Version: v1

GET /foo/bar HTTP/1.1
Host: api.example.com
Accept: application/vnd.example+json;version=1.0

GET /foo/bar HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v1+json

• 客户端token添加版本号

https://api.example.com/foo/bar?token=fc0bfd66c2f3691274982e5f085c2c9c5e54d5b43c5af969395722a74912133c

在服务端处理token的时候，确定请求API的内部版本，再执行具体API。

总结

每个API版本控制的方案没有绝对的好坏，关键在于是否适合所在的场景。
有很多业务需要做版本控制，业务代码兼容过多版本，又会造成代码难以维护的局面，通过运维做多版本控制来处理API服务多版本控制，是一种非常值得推荐的方案。
如果维护的app或者说是API版本过多，必然会导致维护成本大大提高。我们应该统计每个版本的使用量，把使用量较少的版本给干点。另一方面，一些过时的版本我们并不希望用户继续使用时，也可以考虑强制升级。