API版本控制的几种方式

 

2018 年 11 月 3 日 发布

咱们假设API接口的域名名为api.tp5.com，而且以两个版本v1和v2为例（注意，版本号仅为主版本，小版本应该是直接升级，不该该存在共存状况，因此v1.1或者v2.0这种版本号不该该设计在URL里面），来讲明下API版本的不一样控制方式，以及应该如何进行开发的规划。

经过子域名（或子目录）

第一个办法，是直接使用两个模块（或者应用）来实现，对于架构改变比较大的API版本（尤为是不一样版本之间基本无法共用、更改框架甚至采用不一样的语言实现）一般会这样选择。

目录结构以下：

api
├─application           
│  ├─v1  
│  │  ├─controller 
│  │  ├─model 
│  │  ├─config
│  │  └─ ...            
│  ├─v2
│  │  ├─controller
│  │  ├─model           
│  │  ├─config  
│  │  └─ ...     
│   ...

请求方式

GET https://api.tp5.com/v1/user/1
GET https://api.tp5.com/v2/user/1

固然，你也能够经过子域名绑定模块实现下面的方式访问

GET https://v1.api.tp5.com/user/1
GET https://v2.api.tp5.com/user/1

经过请求参数

对于刚开始没有作好版本规划，后期迭代维护过程当中增长了新的版本，考虑到架构的改形成本，可能会考虑下面的方式：

GET https://api.tp5.com/user/1
GET https://api.tp5.com/user/1?version=v2

因为缺少很好的路径和类库目录规范，若是频繁更新版本的话，建议把版本的架构设计升级成后面的两种方式。

经过路由

可能大多数接口在设计的时候已经考虑到了版本控制的问题，那么一般会选择在URL地址中增长版本标识参数，这种方式便于调试。

对于API应用来讲，更建议采用单模块设计+多级控制器，目录结构以下：

api
├─application          
│  ├─controller
│  │  ├─v1
│  │  ├─v2
│  │  └─ ...            
│  ├─model
│   ...

路由规则定义以下：

Route::get(':version/user/:id',':version.User/read');

GET https://api.tp5.com/v1/user/1
GET https://api.tp5.com/v2/user/1

因为使用了多级控制器，须要注意控制器的命名空间。

经过命令行能够快速的建立控制器文件：

php think make:controller v1/User

经过头信息

最新的规范趋向于经过头信息来定义版本，优点在于从历史版本迭代更新的时候不须要改变URL地址，改变请求头信息便可，主要分为两种。

第一种是使用自定义请求头例如api-version控制版本（同理你还能够用其它头信息控制其它）

GET https://api.tp5.com/user/1
api-version:v2

头信息的方式，路由规则的定义略微作下调整便可：

use think\facade\Request;
use think\facade\Route;

$version = Request::header('api-version') ? : 'v1';
Route::get('user/:id', $version . '.User/read');

也有不少采用了Accept头信息来处理（好处是能够设置接口输出格式），一般的规范是

GET https://api.tp5.com/user/1
Accept: application/vnd.tp5.v2+json

总结

对于API接口开发，尽可能事先作好版本控制规划，确保你的应用能兼容新老版本的访问。

 

个人小结：

版本号经过header中的api-version参数传递，而后经过路由来控制访问到具体的控制器和方法

如下是我本身配置的路由：

注意配置路由的时候，“.”分割表示目录名

表示当请求api/任意控制器名/任意方法名时，会访问api/版本目录/任意控制器名/任意方法名

具体的路由规则仍是要看官方文档