版本

你的API應(yīng)該是版本化的。不像你完全控制在客戶端和服務(wù)器端Web應(yīng)用程序代碼, 對于API，您通常沒有對API的客戶端代碼的控制權(quán)。 因此，應(yīng)該盡可能的保持向后兼容性(BC)，如果一些不能向后兼容的變化必須引入 APIs，你應(yīng)該增加版本號。你可以參考Semantic Versioning?有關(guān)設(shè)計(jì)的API的版本號的詳細(xì)信息。

關(guān)于如何實(shí)現(xiàn)API版本，一個(gè)常見的做法是在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)點(diǎn)和缺點(diǎn)， 而且關(guān)于他們也有很多爭論。 下面我們描述在一種API版本混合了這兩種方法的一個(gè)實(shí)用的策略:

• 把每個(gè)主要版本的API實(shí)現(xiàn)在一個(gè)單獨(dú)的模塊ID的主版本號 (例如?v1,?v2)。 自然，API的url將包含主要的版本號。
• 在每一個(gè)主要版本 (在相應(yīng)的模塊)，使用?Accept?HTTP 請求頭 確定小版本號編寫條件代碼來響應(yīng)相應(yīng)的次要版本.

為每個(gè)模塊提供一個(gè)主要版本， 它應(yīng)該包括資源類和控制器類 為特定服務(wù)版本。 更好的分離代碼， 你可以保存一組通用的 基礎(chǔ)資源和控制器類， 并用在每個(gè)子類版本模塊。 在子類中， 實(shí)現(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 屬性當(dāng)它確定 支持哪些內(nèi)容類型時(shí)。

例如， 如果一個(gè)請求通過?Accept: application/json; version=v1被發(fā)送， 內(nèi)容交涉后，yii\web\Response::acceptParams將包含值['version' => 'v1'].

基于?acceptParams?的版本信息，你可以寫條件代碼 如 actions，resource classes，serializers等等。

由于次要版本需要保持向后兼容性，希望你的代碼不會有 太多的版本檢查。否則，有機(jī)會你可能需要創(chuàng)建一個(gè)新的主要版本。