API版本控制

服务API的版本控制历来没有一个完美的解决方案，本篇列出了业界常见的三类API版本控制方案，每一类中又有1到2种实现方式（可能还有更多），看官们可根据自己项目的规模和要求选择适合自己的方案。

---

1. 强制使用统一API版本

整个项目使用一个API版本,每次变更需要考虑向后兼容性，基本原则：只能在原来的结构基础上增加属性，而不能删除，同时需要客户端进行配合。

比如：有个返回值是string类型，如果要变成int类型，不能改变原来的字段值，只能增加一个新的属性，这样才能保证老版本的正常使用。

缺点：返回数据过于冗余，不好判断哪个属性是哪个版本在用，也就无法定期下线指定版本。

2. URI中显式添加版本号

第一种，把版本号嵌入到URL路径中，例如：http://example.com/v3/item/list

第二种，把版本号放在RequestParam中，例如：http://example.com/item/list?version=3

第一种方便在服务端用不同的方法进行版本区分，第二种只能在同一个方法中进行判断区分。

有点：够直观，方便调试。

缺点：不符合RestFull原则（原则又不能当饭吃，解决问题才是王道），版本过多会不好控制。

3. 添加头信息控制版本

第一种， 在Header中添加自定义参数，例如：  api-version: 2 

第二种，在ContentType中添加版本号，例如：Accept: application/vnd.haveibeenpwned.v2+json  或 Accept: application/vnd.haveibeenpwned+json; version=2.0

优点：符合RestFull原则，保持各版本的URL一致。

缺点：不够直观，只能使用带有设置header的工具进行调试。

纵观各大网站的API，使用URL中显示添加版本号的最多，添加头部信息控制版本的次之，几乎没有强制使用统一版本的，so，you know~

关于版本过多难于维护的问题，解决办法是控制API使用周期，最多不超过5个版本同时在使用，并定期下架老旧的API版本。