# 響應格式 當處理一個 RESTful API 請求時， 一個應用程序通常需要如下步驟 來處理響應格式： 1. 確定可能影響響應格式的各種因素， 例如媒介類型， 語言， 版本， 等等。 這個過程也被稱為?[content negotiation](http://en.wikipedia.org/wiki/Content_negotiation)。 2. 資源對象轉換為數組， 如在?[Resources](http://www.yiichina.com/doc/guide/2.0/rest-resources)?部分中所描述的。 通過 yii\rest\Serializer 來完成。 3. 通過內容協商步驟將數組轉換成字符串。 [yii\web\ResponseFormatterInterface|response formatters]] 通過 [yii\web\Response::formatters|response]] 應用程序組件來注冊完成。 ## 內容協商 Yii 提供了通過 yii\filters\ContentNegotiator 過濾器支持內容協商。RESTful API 基于 控制器類 yii\rest\Controller 在`contentNegotiator`?下配備這個過濾器。 文件管理器提供了涉及的響應格式和語言。 例如， 如果一個 RESTful API 請求中包含以下 header， ~~~ Accept: application/json; q=1.0, */*; q=0.1 ~~~ 將會得到JSON格式的響應，如下： ~~~ $ curl -i -H "Accept: application/json; q=1.0, */*; q=0.1" "http://localhost/users" HTTP/1.1 200 OK Date: Sun, 02 Mar 2014 05:31:43 GMT Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y X-Powered-By: PHP/5.4.20 X-Pagination-Total-Count: 1000 X-Pagination-Page-Count: 50 X-Pagination-Current-Page: 1 X-Pagination-Per-Page: 20 Link: <http://localhost/users?page=1>; rel=self, <http://localhost/users?page=2>; rel=next, <http://localhost/users?page=50>; rel=last Transfer-Encoding: chunked Content-Type: application/json; charset=UTF-8 [ { "id": 1, ... }, { "id": 2, ... }, ... ] ~~~ 幕后，執行一個 RESTful API 控制器動作之前，yii\filters\ContentNegotiator filter 將檢查?`Accept`?HTTP header 在請求時和配置 yii\web\Response::format 為?`'json'`。 之后的動作被執行并返回得到的資源對象或集合， yii\rest\Serializer 將結果轉換成一個數組。最后，yii\web\JsonResponseFormatter 該數組將序列化為JSON字符串，并將其包括在響應主體。 默認, RESTful APIs 同時支持JSON和XML格式。為了支持新的格式，你應該 在?`contentNegotiator`?過濾器中配置 yii\filters\ContentNegotiator::formats 屬性， 類似如下 API 控制器類: ~~~ use yii\web\Response; public function behaviors() { $behaviors = parent::behaviors(); $behaviors['contentNegotiator']['formats']['text/html'] = Response::FORMAT_HTML; return $behaviors; } ~~~ `formats`?屬性的keys支持 MIME 類型，而 values 必須在 yii\web\Response::formatters 中支持被響應格式名稱。 ## 數據序列化 正如我們上面所描述的，yii\rest\Serializer 負責轉換資源的中間件 對象或集合到數組。它將對象 yii\base\ArrayableInterface 作為 yii\data\DataProviderInterface。 前者主要由資源對象實現， 而 后者是資源集合。 你可以通過設置 yii\rest\Controller::serializer 屬性和一個配置數組。 例如，有時你可能想通過直接在響應主體內包含分頁信息來 簡化客戶端的開發工作。這樣做，按照如下規則配置 yii\rest\Serializer::collectionEnvelope 屬性： ~~~ use yii\rest\ActiveController; class UserController extends ActiveController { public $modelClass = 'app\models\User'; public $serializer = [ 'class' => 'yii\rest\Serializer', 'collectionEnvelope' => 'items', ]; } ~~~ 那么你的請求可能會得到的響應如下?`http://localhost/users`: ~~~ HTTP/1.1 200 OK Date: Sun, 02 Mar 2014 05:31:43 GMT Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y X-Powered-By: PHP/5.4.20 X-Pagination-Total-Count: 1000 X-Pagination-Page-Count: 50 X-Pagination-Current-Page: 1 X-Pagination-Per-Page: 20 Link: <http://localhost/users?page=1>; rel=self, <http://localhost/users?page=2>; rel=next, <http://localhost/users?page=50>; rel=last Transfer-Encoding: chunked Content-Type: application/json; charset=UTF-8 { "items": [ { "id": 1, ... }, { "id": 2, ... }, ... ], "_links": { "self": { "href": "http://localhost/users?page=1" }, "next": { "href": "http://localhost/users?page=2" }, "last": { "href": "http://localhost/users?page=50" } }, "_meta": { "totalCount": 1000, "pageCount": 50, "currentPage": 1, "perPage": 20 } } ~~~