Yii2.0 初识 RESTful Serializer

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

所以打开Yii框架下的vendor/yiisoft/yii2/rest/Serializer.php

    public $fieldsParam = 'fields';
   
    public $expandParam = 'expand';
    
    public $totalCountHeader = 'X-Pagination-Total-Count';
   
    public $pageCountHeader = 'X-Pagination-Page-Count';
   
    public $currentPageHeader = 'X-Pagination-Current-Page';
    
    public $perPageHeader = 'X-Pagination-Per-Page';
    
    public $collectionEnvelope;
   
    public $linksEnvelope = '_links';
    
    public $metaEnvelope = '_meta';
    
    public $request;
   
    public $response;

变量$fieldsParam对应的是是RESTful风格中的yii\base\Model::fields()或者yii\db\ActiveRecord::fields()方法的返回值结果为一个键值对数组

例如：

public function fields(){   return [   // 字段名和属性名相同 'id', // 字段名为"email", 对应的属性名为"email_address"  'email' => 'email_address',   // 字段名为"name", 值由一个PHP回调函数定义 'name' => function ($model) {  return $model->first_name . ' ' . $model->last_name;  },    ];}

那么对应的当该资源被请求时返回的将是：

[ // 字段名和属性名相同 'id', // 字段名为"email", 对应的属性名为"email_address" 'email' => 'email_address', // 字段名为"name", 值由一个PHP回调函数定义 'name' => function ($model) { return $model->first_name . ' ' . $model->last_name; },  ]

如果对应的模型层中没有实现yii\base\Model::fields()或者yii\db\ActiveRecord::fields()方法，则会默认返回所有定义的字段。

变量$expandParam对应的是yii\db\Model::extraFields() 和 yii\db\ActiveRecord::extraFields() 其中前者返回空值，后者返回关联模型中定义的字段键值对数组，实现方法与yii\base\Model::fields()或者yii\db\ActiveRecord::fields()相同。

变量$totalCountHeader当请求资源时如果设置了分页，那么$totalCountHeader对应资源请求中的总的记录数量。

变量$pageCountHeader当请求资源时如果设置了分页，那么$pageCountHeader对应资源请求中的分页总数。

变量$currentPageHeader当请求资源时如果设置了分页，那么$currentPageHeader对应资源请求中的当前的页码。

变量$perPageHeader当请求资源时如果设置了分页，那么$perPageHeader对应资源请求中每一页的记录数量。

变量$collectionEnvelope，当发出一个资源请求，其中包括了对分页的要求或者对于关联操作进行的设置，那么$collectionEnvelope就会有对应的值。

首先是返回的关联操作，统一的是以资源请求的url形式进行返回的，声明的时候会有譬如最典型的返回一个self链接：

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

那么在我们得到的资源中将会有：

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

增加了一个_links标记 其中包括了我们在添加的yii\db\ActiveRecord::getLinks()中添加的url，而这个标签内的内容恰好是变量$linksEnvelope对应的，如果设置了分页那么类似_links标记，还会增加一个_meta标记由$metaEnvelope对应：

'_meta' => {    // meta information as returned by Pagination::toArray()
    'totalCount' => 100,
    'pageCount' => 5,
    'currentPage' => 1,
    'perPage' => 20,
}

对于变量的解释就到这里，接下来是对方法部分的解释。

init()方法：

 public function init()
 {
     if ($this->request === null) {
         $this->request = Yii::$app->getRequest();
     }
     if ($this->response === null) {
         $this->response = Yii::$app->getResponse();
     }
 }

每次初始化时会初始化$request和$response的值，这两个变量的实现参考vendor/yiisoft/yii2/web/Request.php

和vendor/yiisoft/yii2/web/Respense.php 就是对数据的接收的返回的解析和封装，这里不做赘述。

serialize()方法：

    public function serialize($data)
    {
        if ($data instanceof Model && $data->hasErrors()) {
            return $this->serializeModelErrors($data);
        } elseif ($data instanceof Arrayable) {
            return $this->serializeModel($data);
        } elseif ($data instanceof DataProviderInterface) {
            return $this->serializeDataProvider($data);
        } else {
            return $data;
        }
    }

这一步是对数据进行序列化，将数据格式统一处理为标准的RESTful的数据格式，便于开发者操作处理。

首先看是第一个条件，判断了$data是否为符合要求的数据，此处调用的yii\base\Model::hasErrors()方法的代码如下：

    public function hasErrors($attribute = null)
    {
        return $attribute === null ? !empty($this->_errors) : isset($this->_errors[$attribute]);
    }

当传入数据没有属性，或者数据有属性是否存在不符（通过数据层中实现的rules()方法检验）。

如果数据符合要求则会进入下面的序列化阶段，如果传入的数据为键值对那么使用serializeModel()方法：

protected function serializeModel($model)
    {
        if ($this->request->getIsHead()) {
            return null;
        } else {
            list ($fields, $expand) = $this->getRequestedFields();
            return $model->toArray($fields, $expand);
        }
    }

首先用yii2/web/Request::getIsHead()方法来判断当前的请求是否为HEAD请求是的话不返回信息，如果不是则通过getRequestedFields()方法对数据进行序列化，代码如下：

    protected function getRequestedFields()
    {
        $fields = $this->request->get($this->fieldsParam);
        $expand = $this->request->get($this->expandParam);


        return [
            preg_split('/\s*,\s*/', $fields, -1, PREG_SPLIT_NO_EMPTY),
            preg_split('/\s*,\s*/', $expand, -1, PREG_SPLIT_NO_EMPTY),
        ];
    }

首先调用yii2/web/Request::get()方法

    public function get($name = null, $defaultValue = null)
    {
        if ($name === null) {
            return $this->getQueryParams();
        } else {
            return $this->getQueryParam($name, $defaultValue);
        }
    }    public function getQueryParam($name, $defaultValue = null)     {         $params = $this->getQueryParams();         return isset($params[$name]) ? $params[$name] : $defaultValue;     } 

去掉请求中的空格并且返回非空部分作为标签名。然后由serialize()返回该值。

如果传入的数据类型是根据DataProviderInterface接口实现的，那么则需要根据传入的分页信息对数据进行处理。

关于Yii的Arrayable接口，详情请见官方文档