上篇写《聊聊数据库和缓存同步机制》的时候，收到一份读者留言，希望我来谈谈API开发过程中的版本控制。这是一个很好的话题，对于任何互联网产品，随着需求的改进，都会遇到同样的问题，我自己也被这个问题困扰过。所以今天我尝试来做一个总结，将我过去不同项目中遇到的API版本控制方案罗列出来，给大家做一个参考，希望对朋友们有所帮助。
API版本控制模式
首先我们先谈谈，API的版本控制的3种模式：
1. 不设定版本模式
意味着每个API只提供一个版本，如果要修改本API, 所有的用户都必须使用最新的API，任何API的修改都会影响到所有的用户。
2.API自带版本模式
同一个名称的API可以建立多个版本，API调用方根据自己的需求选择使用对应的API版本。新版本与老版本共存，意味着老版本用户不会受新版本更新的影响。
3. 兼容性版本模式
每个API只有一个版本，API需要兼容以前老版本API的功能。所有版本用户都调用同一个API，通过内在代码保证兼容性。
从实战看，单纯使用模式1的情况会比较少，主要使用模式2或者模式3。
API版本控制的执行方案
对于上文提到的3种版本控制模式，接下来，我们来讲讲如何来落地执行每种模式：
无版本模式的可选执行方案
新功能直接在老API上修改，强制调用方客户端（iOS/Android/H5）升级，用户体验会受到影响，也有一定的技术难度，适用场景比较有限。
更换API名称，新功能使用新的API名字，新版本客户端调用新名称API，例如：
http://jiagouzhan.com/api/user/login
http://jiagouzhan.com/api/user/newLogin
API自带版本模式的可选执行方案
1. URI上添加版本号，URI中直接标记使用的是哪个版本，无版本号URI默认使用最新版本。
http://jiagouzhan.com/api/user/list
http://jiagouzhan.com/api/v2/user/list
2. 参数带版本号，即在每个API请求后添加一个version参数，表示请求的是哪个版本。
http://jiagouzhan.com/api/user/list?Version=2
兼容性版本模式的可选执行方案
基于版本模式的改进方案，将版本从API中“隐藏”起来。
通过HTTP头部做版本指定
在处理API请求的时候，服务端根据API调用方在request header中设置的api-version来判断，进而执行不同的逻辑处理分支，如以下所示，以此实现版本的兼容性。
GET http://jiagouzhan.com/api/user/list
Host: jiagouzhan.com
Cache-Control: no-cache
Referer: http://download.google.com/
User-Agent:Mozilla/4.04[en](Win95;I;Nav)
Range:bytes=554554-
api-version: v1
2. 通过客户端token进行控制
客户端与服务端交互的时候，都会有一个token字段，我们选择在token上“做文章”，服务端实现一个token处理器，用于token与版本的映射，具体的步骤如下：
http://jiagouzhan.com/api/user/list?token=5782b5e0512c7d47345d10af413b3d28
-----> 服务端token处理器处理 ------> 确定请求API的内部版本 -----> 执行具体API ------>返回结果
这样做，有两个明显的好处：
1. 在一定程度上防止了很多无效的请求，如果使用的是https传递信息，就更安全了，阻止外部攻击者利用API请求攻击服务端，由于拿不到token, 即便清楚API的接口名称和路径，也根本无法突破API网关，到达服务内部。
2. 服务端可以灵活的配置接口，客户端只要每次请求的时候带上默认的token参数，就可以得到客户端想要的了，完全不需要关心版本的问题，对版本做到透明。
对API版本控制方案的描述告一段落了，明眼人心里一定清楚我推荐使用那个方案了。:) 不过，方案没有绝对的好坏，关键还在于是否适合所在的场景。如果你有更好的方案，欢迎留言交流。
扫描二维码或手动搜索微信公众号【架构栈】： ForestNotes
网友评论