?
This document uses PHP Chinese website manual Release
版本
版本
你的API應(yīng)該是版本化的。不像你完全控制在客戶端和服務(wù)器端Web應(yīng)用程序代碼, 對于API，您通常沒有對API的客戶端代碼的控制權(quán)。 因此，應(yīng)該盡可能的保持向后兼容性(BC)，如果一些不能向后兼容的變化必須引入 APIs，你應(yīng)該增加版本號。你可以參考Semantic Versioning?有關(guān)設(shè)計的API的版本號的詳細信息。
關(guān)于如何實現(xiàn)API版本，一個常見的做法是在API的URL中嵌入版本號。 例如，http://example.com/v1/users代表/users版本1的API. 另一種API版本化的方法最近用的非常多的是把版本號放入HTTP請求頭，通常是通過Accept頭， 如下：
// 通過參數(shù)Accept: application/json; version=v1
// 通過vendor的內(nèi)容類型Accept: application/vnd.company.myapp-v1+json
這兩種方法都有優(yōu)點和缺點， 而且關(guān)于他們也有很多爭論。 下面我們描述在一種API版本混合了這兩種方法的一個實用的策略:
- 把每個主要版本的API實現(xiàn)在一個單獨的模塊ID的主版本號 (例如?
v1,?v2)。 自然，API的url將包含主要的版本號。 - 在每一個主要版本 (在相應(yīng)的模塊)，使用?
Accept?HTTP 請求頭 確定小版本號編寫條件代碼來響應(yīng)相應(yīng)的次要版本.
為每個模塊提供一個主要版本， 它應(yīng)該包括資源類和控制器類 為特定服務(wù)版本。 更好的分離代碼， 你可以保存一組通用的 基礎(chǔ)資源和控制器類， 并用在每個子類版本模塊。 在子類中， 實現(xiàn)具體的代碼例如?Model::fields()。
你的代碼可以類似于如下的方法組織起來：
api/
common/
controllers/
UserController.php
PostController.php
models/
User.php
Post.php
modules/
v1/
controllers/
UserController.php
PostController.php
models/
User.php
Post.php
v2/
controllers/
UserController.php
PostController.php
models/
User.php
Post.php你的應(yīng)用程序配置應(yīng)該這樣：
return [
'modules' => [
'v1' => [
'basePath' => '@app/modules/v1',
],
'v2' => [
'basePath' => '@app/modules/v2',
],
],
'components' => [
'urlManager' => [
'enablePrettyUrl' => true,
'enableStrictParsing' => true,
'showScriptName' => false,
'rules' => [
['class' => 'yii\rest\UrlRule', 'controller' => ['v1/user', 'v1/post']],
['class' => 'yii\rest\UrlRule', 'controller' => ['v2/user', 'v2/post']],
],
],
],
];
因此，http://example.com/v1/users將返回版本1的用戶列表，而?http://example.com/v2/users將返回版本2的用戶。
使用模塊， 將不同版本的代碼隔離。 通過共用基類和其他類 跨模塊重用代碼也是有可能的。
為了處理次要版本號， 可以利用內(nèi)容協(xié)商 功能通過 yii\filters\ContentNegotiator 提供的行為。contentNegotiator?行為可設(shè)置 yii\web\Response::acceptParams 屬性當它確定 支持哪些內(nèi)容類型時。
例如， 如果一個請求通過?Accept: application/json; version=v1被發(fā)送， 內(nèi)容交涉后，yii\web\Response::acceptParams將包含值['version' => 'v1'].
基于?acceptParams?的版本信息，你可以寫條件代碼 如 actions，resource classes，serializers等等。