### 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接口開發，盡量事先做好版本控制規劃，確保你的應用能兼容新老版本的訪問。