restful 接口版本控制

做RESTful开放平台，一方面其API变动越少，对API调用者越有利；另一方面，没有人可以预测未来，系统在发展的过程中，不可避免的需要添加新的资源，或者修改现有资源。

因此，改动升级必不可少，但是，作为平台开发者，你必须有觉悟：一旦你的API开放出去，有人开始用了，你就不能只管自己Happy了，你对平台的任何改动都需要考虑对当前用户的影响。

因此，做开放平台，你从第一个API的设计就需要开始API的版本控制策略问题，API的版本控制策略就像是开放平台和平台用户之间的长期协议，其设计的好坏将直接决定用户是否使用该平台，或者说用户在使用之后是否会因为某次版本升级直接弃用该平台。

API的版本控制策略通常有3种模式：

第一种：The Knot

无版本，即平台的API永远只有一个版本，所有的用户都必须使用最新的API，任何API的修改都会影响到平台所有的用户。甚至平台的整个生态系统。 目前我是没有见过哪家公司能够这么硬气的

第二种：Point-to-Point

点对点，即平台的API版本自带版本号，用户根据自己的需求选择使用对应的API，需要使用新的API特性，用户必须自己升级。目前也是我司采用的一个方法。我会着重来讲这种方法下的接口版本控制。

第三种：Compatible Versioning

兼容性版本控制，和The Knot一样，平台只有一个版本，但是最新版本需要兼容以前版本的API行为。

现实问题

从用户来讲：我不想升级，道理很简单，浪费精力。
产品：一起以用户为中心

从这个点来说，第一种和第三种就不能搞定了。第三种为什么不能应对这种需求呢，其实我们实际开发过程中就难免不了出现新旧版本不兼容的问题。举个例子，用户发帖，最开始产品考虑很多，发帖需要带发帖定位，后面发现用户都对这种很抵触，那么后续发帖就把这个字段删掉了。那么我们之前的接口需要传入这个参数，现在来说的话如果我服务端只有一个接口，那么后续的话我们必须冗余一个字段去兼容旧版本，长此以往，就会变成一个不可维护的接口了。

针对上面的论述，首先，API一定得有版本，否则升级对于用户来说将是噩梦。其次，要做到Compatible Versioning有现实的限制，毕竟API升级时，不可避免的会出现无法兼容老版本的状况，因此，版本控制需要结合第二种和第三种模式，即提供一个统一的兼容版本入口，同时对于不能兼容历史版本的API保留历史版本，支持用户能够调用到历史版本的API。另外，对历史版本的API支持一定要有时间和用户限制，即老版API支持到一定时间就删除，新用户必须使用新版API，否则一个API有10个版本会让平台的维护，这是非常痛苦。

传参操作

不同版本的app我们如何来进行
URI vs Request Parameter vs Media Type
在RESTful API领域，关于如何做版本控制，目前业界比较主流的有3种做法：

(一) URI

即在URI中直接标记使用的是哪个版本，无版本号URI默认使用最新版本。如下：

http://xianlinbox/api/customers/1234 
http://xianlinbox/api/v3.0/customers/1234

• 好处：
  直接可以在URI中直观的看到API版本，可以直接在浏览器的查看各个版本API的结果.
• 坏处：
  版本号在URI中破坏了REST的HATEOAS（hypermedia as the engine of application state）规则。版本号和资源之间并无直接关系。

(二) Request Parameter

即在每个请求后添加一个version参数，表示请求的是哪个版本。如下：

http://server:port/api/customer/123?version=2

(三) Mdedia Type

即在HTTP请求的header中使用Media Type标记该请求想获取的资源， 同样的可以不设置或设置通用的Media Type表示最新版本的API。

这种就是在header头上加版本控制，curl暂时不写了

后端操作

• 方法一：后台维护多个版本的接口，每次建立新版本copy整个文件，在新文件上修改。这个方法其实真的很困难，大版本迭代其实没啥问题，如果是敏捷开发，一到两个周上一个版本这个问题就很大了。之前我们代码大概是这个样子的

├── v1.1
├── v1.12
├── v1.3
└── v1.4

然后内部的结构几乎什么都一样的。然后在外部的路由文件引入每个版本单独的路由，如果我开一个新版本，我需要把上个版本的所有的文件copy一份：cp -r v1.4 v.15 。之前的大版本因为改的接口多，所以没有问题，现在改换开发模式为敏捷，我们几乎要管理包引用问题，每个文件夹下近百个文件。所以每个版本迭代是非常让后台苦恼的。

• 方法二：目前也是我们公司实践的一种方式：copy目录结构，将新增，修改的api写在新版本中，完整copy路由，将修改的和新增的api添加到最新版本。然后将未修改的新版api指向之前的版本的方法。不过目前感觉还是不够优雅，但是按照逻辑来说的话是最优解了。

后续发展

目前公司有部分业务已经逐渐步入微服务了，我们打算进一步探索微服务的版本控制，看是否还能通过路由带参数来控制后台返回，将再接下来的文章中展示