資源

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

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

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

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

字段

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

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

// 返回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() 只返回和數(shù)據(jù)表關聯(lián)的屬性作為字段。

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

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

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

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

    return $fields;
}

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

覆蓋?extraFields()?方法

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

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

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

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

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

[
    {
        "id": 100,
        "email": "100@example.com",
        "profile": {
            "id": 100,
            "age": 30,
        }
    },
    ...
]

鏈接

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

資源類通過實現(xiàn)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": "user@example.com",
    // ...
    "_links" => {
        "self": {
            "target="_blank" href": "https://example.com/users/100"
        }
    }
}

集合

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

集合可被展現(xiàn)成數(shù)組，更多情況下展現(xiàn)成?data providers. 因為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響應中發(fā)送data provider 時， yii\rest\Serializer 會取出資源的當前頁并組裝成資源對象數(shù)組， yii\rest\Serializer 也通過如下HTTP頭包含頁碼信息：

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