0 关注者

资源 ¶

字段
链接
集合

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 转换为数组。其次，数组由响应格式化程序以请求的格式（例如 JSON、XML）序列化为字符串。在开发资源类时，您应该主要关注第一步。

通过重写 fields() 和/或 extraFields()，您可以指定资源中的哪些数据（称为字段）可以放入其数组表示形式中。这两种方法的区别在于，前者指定应包含在数组表示形式中的默认字段集，而后者指定如果最终用户通过 expand 查询参数请求，则可以包含在数组中的其他字段。例如，

// returns all fields as declared in fields()
http://localhost/users

// only returns "id" and "email" fields, provided they are declared in fields()
http://localhost/users?fields=id,email

// returns all fields in fields() and field "profile" if it is in extraFields()
http://localhost/users?expand=profile

// returns all fields in fields() and "author" from post if
// it is in extraFields() of post model
http://localhost/comments?expand=post.author

// only returns "id" and "email" provided they are in fields() and "profile" if it is in extraFields()
http://localhost/users?fields=id,email&expand=profile

重写 `fields()` ¶

默认情况下，yii\base\Model::fields() 返回所有模型属性作为字段，而 yii\db\ActiveRecord::fields() 仅返回已从数据库填充的属性。

您可以重写 fields() 以添加、删除、重命名或重新定义字段。fields() 的返回值应为数组。数组键是字段名，数组值是相应的字段定义，可以是属性名或返回相应字段值的匿名函数。在字段名与其定义的属性名相同的情况下，您可以省略数组键。例如，

// explicitly list every field, best used when you want to make sure the changes
// in your DB table or model attributes do not cause your field changes (to keep API backward compatibility).
public function fields()
{
    return [
        // field name is the same as the attribute name
        'id',
        // field name is "email", the corresponding attribute name is "email_address"
        'email' => 'email_address',
        // field name is "name", its value is defined by a PHP callback
        'name' => function ($model) {
            return $model->first_name . ' ' . $model->last_name;
        },
    ];
}

// filter out some fields, best used when you want to inherit the parent implementation
// and exclude some sensitive fields.
public function fields()
{
    $fields = parent::fields();

    // remove fields that contain sensitive information
    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，是超媒体作为应用状态引擎的缩写，提倡 RESTful API 应该返回允许客户端发现返回资源支持的操作的信息。HATEOAS 的关键是在 API 提供资源数据时返回一组带有关系信息的超链接。

您的资源类可以通过实现yii\web\Linkable接口来支持 HATEOAS。该接口包含一个名为getLinks()的方法，该方法应该返回一个链接列表。通常，您应该至少返回表示资源对象本身的 URL 的self链接。例如：

use yii\base\Model;
use yii\web\Link; // represents a link object as defined in JSON Hypermedia API Language.
use yii\web\Linkable;
use yii\helpers\Url;

class UserResource extends Model implements Linkable
{
    public $id;
    public $email;

    //...

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

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

    public function getLinks()
    {
        return [
            Link::REL_SELF => Url::to(['user/view', 'id' => $this->id], true),
            'edit' => Url::to(['user/view', 'id' => $this->id], true),
            'profile' => Url::to(['user/profile/view', 'id' => $this->id], true),
            'index' => Url::to(['users'], true),
        ];
    }
}

当在响应中返回UserResource对象时，它将包含一个_links元素，表示与用户相关的链接，例如：

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

集合 ¶

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

虽然集合可以表示为数组，但通常更希望将其表示为数据提供程序。这是因为数据提供程序支持资源的排序和分页，这是 RESTful API 返回集合时常用的功能。例如，以下操作返回有关帖子资源的数据提供程序

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(),
        ]);
    }
}