API接口多版本维护设计与实现

1、api版本号放在url路径中
https://api.example.com/v1/user/ID
https://api.example.com/v2/user/ID
https://api.example.com/v3/user/ID
https://api.example.com/user/v1/ID
https://api.example.com/user/v2/ID
https://api.example.com/user/v3/ID

代码一：

代码二：

2、api版本号放在url参数中
https://api.example.com/user/ID?version=v1&…
https://api.example.com/user/ID?version=v2&…
https://api.example.com/user/ID?version=v3&…
这种做起来比较简单也容易理解，但是在你的每个接口逻辑里面都需要写判断版本的代码。例如：

这样的代码看起来感觉很不舒服。而且会维护一大堆的if-else，以后会越来越长
3、api版本号放在请求的header中
客户端在做请求的时候，在HTTP HEAD里面中添加API-VERSION字段，标识出请求的是哪个接口：
-H “API-VERSION: v1”
-H “API-VERSION: v2”
这个需要统一做的事情稍微有点多，但之后的接口逻辑会比较好些。在入口的地方获取接口版本，然后把请求分发到对应版本的接口处理器上
4、api版本号放在二级域名中
不同版本使用不同的域名，例如：
v1.api.xxx.com
v2.api.xxx.com
域名的方式可以采用下面的两种方式：
不同版本的api部署成不同的应用（甚至可以部署到不同的服务器上），彼此间独立，其好处是部署的过程不会影响其他版本api的使用，并且可以减轻单台服务器的负担。
部署在一个应用上面，但是和第三种一样，在接口入口处分发到不同版本的接口处理器上进行处理。好处是不同版本间能够直接复用相同的功能。

总结
主要有2种方案：
1：同一套代码，兼容不同版本的api。根据请求中的版本信息区分，返回不同的数据。 （倾向于选方案1）
2：严格区分个版本api的代码，使用不同的分支或是tags，分布部署不同版本api对应的服务（分开部署，倾向于选方案4）

• 整个产品的生命周期中接口的数目和功能可能会不停的增加，但对于某个接口而言，不会频繁的变动（修改接口的输入输出约定），而增加接口对于老的接口是没有影响的，也就不会到必须升级接口的地步（你的老app只是在用原来就存在的老接口而已，新增加的接口对它没有影响）

• 如果接口变化已经到了今天V1、明天V2、后天V3的地步，就得重新考虑开始对产品的需求是否足够准确（需要维护的接口文档会让人头疼）

• 不同版本接口相互独立在某种程度上限制了开发人员，随随便便就v1、v2、v3

• 接口版本信息能够直接在url里面体现，清晰易懂，也比较容易做接口调试

• 不同的版本的api应用（或者接口处理器）之间彼此独立，符合软件工程的低耦合原则

• 做好版本使用监控。当观察到所有用户都使用新版本的客户端的时候，并保持一段时间的时候。放弃对老版本的维护，继而下掉老版本的资源。当然，万不得已的时候，还可以用强制更新。