Yii2.0 RESTful Web服務（2）

資源

RESTful 的 API 都是關於訪問和操作資源，可將資源看成MVC模式中的Model

在如何代表一個資源沒有固定的限定，在Yii中通常使用 yii\base\Model 或它的子類（如 yii\db\ActiveRecord） 代表資源，是爲以下原因：

• yii\base\Model 實現了 yii\base\Arrayable 接口，它允許你通過RESTful API自定義你想要公開的資源數據。
• yii\base\Model 支持輸入驗證, 在你的RESTful API需要支持數據輸入時非常有用。
• yii\db\ActiveRecord 提供了強大的數據庫訪問和操作方面的支持，如資源數據需要存到數據庫它提供了完美的支持。（關於ActiveRecord）

本節主要描述資源類如何從 yii\base\Model (或它的子類) 繼承並指定哪些數據可通過RESTful API返回，如果資源類沒有 繼承 yii\base\Model 會將它所有的公開成員變量返回。

字段 

當RESTful API響應中包含一個資源時，該資源需要序列化成一個字符串。 Yii將這個過程分成兩步，首先，資源會被yii\rest\Serializer轉換成數組， 然後，該數組會通過yii\web\ResponseFormatterInterface根據請求格式(如JSON, XML)被序列化成字符串。 當開發一個資源類時應重點關注第一步。

通過覆蓋 yii\base\Model::fields() 和/或 yii\base\Model::extraFields() 方法, 可指定資源中稱爲 字段 的數據放入展現數組中，兩個方法的差別爲前者指定默認包含到展現數組的字段集合， 後者指定由於終端用戶的請求包含 expand 參數哪些額外的字段應被包含到展現數組，例如，

// 返回fields()方法中申明的所有字段
http://localhost/users

// 只返回fields()方法中申明的id和email字段
http://localhost/users?fields=id,email

// 返回fields()方法申明的所有字段，以及extraFields()方法中的profile字段
http://localhost/users?expand=profile

// 返回回fields()和extraFields()方法中提供的id, email 和 profile字段
http://localhost/users?fields=id,email&expand=profile

覆蓋 fields() 方法 

yii\base\Model::fields() 默認返回模型的所有屬性作爲字段， yii\db\ActiveRecord::fields() 只返回和數據表關聯的屬性作爲字段。

可覆蓋 fields() 方法來增加、刪除、重命名、重定義字段，fields() 的返回值應爲數組，數組的鍵爲字段名 數組的值爲對應的字段定義，可爲屬性名或返回對應的字段值的匿名函數，特殊情況下，如果字段名和屬性名相同， 可省略數組的鍵，例如

// 明確列出每個字段，適用於你希望數據表或模型屬性修改時不導致你的字段修改（保持後端API兼容性）
public function fields()
{
    return [
        // 字段名和屬性名相同
        'id',
        // 字段名爲"email", 對應的屬性名爲"email_address"
        'email' => 'email_address',
        // 字段名爲"name", 值由一個PHP回調函數定義
        'name' => function ($model) {
            return $model->first_name . ' ' . $model->last_name;
        },
    ];
}

// 過濾掉一些字段，適用於你希望繼承父類實現同時你想屏蔽掉一些敏感字段
public function fields()
{
    $fields = parent::fields();

    // 刪除一些包含敏感信息的字段
    unset($fields['auth_key'], $fields['password_hash'], $fields['password_reset_token']);

    return $fields;
}

警告: 模型的所有屬性默認會被包含到API結果中，應檢查數據確保沒包含敏感數據，如果有敏感數據， 應覆蓋fields()過濾掉，在上述例子中，我們選擇過濾掉 auth_key, password_hash 和 password_reset_token.

覆蓋 extraFields() 方法 

yii\base\Model::extraFields() 默認返回空值，yii\db\ActiveRecord::extraFields() 返回和數據表關聯的屬性。

extraFields() 返回的數據格式和 fields() 相同，一般extraFields() 主要用於指定哪些值爲對象的字段， 例如，給定以下字段申明

public function fields()
{
    return ['id', 'email'];
}

public function extraFields()
{
    return ['profile'];
}

http://localhost/users?fields=id,email&expand=profile 的請求可能返回如下JSON 數據:

[
    {
        "id": 100,
        "email": "[email protected]",
        "profile": {
            "id": 100,
            "age": 30,
        }
    },
    ...
]

鏈接 

HATEOAS, 是Hypermedia as the Engine of Application State的縮寫, 提升RESTful API 應返回允許終端用戶訪問的資源操作的信息，HATEOAS 的目的是在API中返回包含相關鏈接信息的資源數據。 

資源類通過實現yii\web\Linkable 接口來支持HATEOAS，該接口包含方法 yii\web\Linkable::getLinks() 來返回 yii\web\Link 列表，典型情況下應返回包含代表本資源對象URL的 self 鏈接，例如

use yii\db\ActiveRecord;
use yii\web\Link;
use yii\web\Linkable;
use yii\helpers\Url;

class User extends ActiveRecord implements Linkable
{
    public function getLinks()
    {
        return [
            Link::REL_SELF => Url::to(['user/view', 'id' => $this->id], true),
        ];
    }
}

當響應中返回一個User 對象，它會包含一個 _links 單元表示和用戶相關的鏈接，例如

{
    "id": 100,
    "email": "[email protected]",
    // ...
    "_links" => {
        "self": {
            "href": "https://example.com/users/100"
        }
    }
}

集合 

資源對象可以組成 集合，每個集合包含一組相同類型的資源對象。

集合可被展現成數組，更多情況下展現成data provider. 因爲data providers支持資源的排序和分頁，這個特性在 RESTful API 返回集合時也用到，例如This is because data providers support sorting and pagination 如下操作返回post資源的data provider:

namespace app\controllers;

use yii\rest\Controller;
use yii\data\ActiveDataProvider;
use app\models\Post;

class PostController extends Controller
{
    public function actionIndex()
    {
        return new ActiveDataProvider([
            'query' => Post::find(),
        ]);
    }
}

當在RESTful API響應中發送data provider 時， yii\rest\Serializer 會取出資源的當前頁並組裝成資源對象數組， yii\rest\Serializer 也通過如下HTTP頭包含頁碼信息：

• X-Pagination-Total-Count: 資源所有數量;
• X-Pagination-Page-Count: 頁數;
• X-Pagination-Current-Page: 當前頁(從1開始);
• X-Pagination-Per-Page: 每頁資源數量;
• Link: 允許客戶端一頁一頁遍歷資源的導航鏈接集合.