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/版本目錄/任意控制器名/任意方法名

具體的路由規則仍是要看官方文檔