阅读 5101

谈谈API版本控制的策略


上篇写《聊聊数据库和缓存同步机制》的时候,收到一份读者留言,希望我来谈谈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种版本控制模式,接下来,我们来讲讲如何来落地执行每种模式:


无版本模式的可选执行方案


  1. 新功能直接在老API上修改,强制调用方客户端(iOS/Android/H5)升级,用户体验会受到影响,也有一定的技术难度,适用场景比较有限。

  2. 更换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中“隐藏”起来。


  1. 通过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

欢迎转载,带上以下二维码即可



关注下面的标签,发现更多相似文章
评论