Yii 中文社区 · 更新于 2017-12-16 11:00:59

资源

RESTful 的 API 都是关于访问和操作 资源,可将资源看成 MVC 模式中的模型

在如何代表一个资源没有固定的限定,在 Yii 中通常使用 [[yii\base\Model]] 或它的子类(如 [[yii\db\ActiveRecord]])代表资源,是为以下原因:

  • [[yii\base\Model]] 实现了 [[yii\base\Arrayable]] 接口,它允许你通过 RESTful API 自定义你想要公开的资源数据。
  • [[yii\base\Model]] 支持 输入验证, 在你的 RESTful API 需要支持数据输入时非常有用。
  • [[yii\db\ActiveRecord]] 提供了强大的数据库访问和操作方面的支持,如资源数据需要存到数据库它提供了完美的支持。

本节主要描述资源类如何从 [[yii\base\Model]] (或它的子类) 继承并指定哪些数据可通过 RESTful API 返回,如果资源类没有继承 [[yii\base\Model]] 会将它所有的公开成员变量返回。

字段

当 RESTful API 响应中包含一个资源时,该资源需要序列化成一个字符串。Yii 将这个过程分成两步,首先,资源会被[[yii\rest\Serializer]]转换成数组,然后,该数组会通过[[yii\web\ResponseFormatterInterface|response formatters]]根据请求格式(如 JSON, XML)被序列化成字符串。当开发一个资源类时应重点关注第一步。

通过覆盖 [[yii\base\Model::fields()|fields()]] 和/或 [[yii\base\Model::extraFields()|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_hashpassword_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": "100@example.com",
        "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()|getLinks()]] 来返回[[yii\web\Link|links]] 列表,典型情况下应返回包含代表本资源对象 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": {
            "href": "https://example.com/users/100"
        }
    }
}

集合

资源对象可以组成 集合,每个集合包含一组相同类型的资源对象。

集合可被展现成数组,更多情况下展现成 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 响应中发送 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: 允许客户端一页一页遍历资源的导航链接集合.

可在快速入门 一节中找到样例.

上一篇: 快速入门 下一篇: 控制器