第四節：dingo/API 最新版 V2.0 之 Responses （連載）
因為某些某些原因，不能按時更新，唉。我會盡力，加快速度。（這句話不是翻譯的哈）
原文地址——> https://github.com/dingo/api/wiki/Responses
A functioning API is built upon receiving requests and returning a consumable response to the client. An API will generally return responses in an easy to consume format such as JSON. There‘s a number of different ways to return responses and it will largely depend on how complex your API is or will become.
一個運行的API 主要是獲取請求並返回給客戶端響應信息。一個API通常會以一種易於使用的格式返回響應，例如JSON。這是一個不同的方法去返回請求。這裏有許多不同的方法可以返回響應，很大程度上取決於您的API的復雜程度或者API未來的方向。
The easiest way to return a consumable response is to simply return an array or object directly from your controller. Not every object can be correctly formatted though so you should ensure that it implements either the ArrayObject
Illuminate\Support\Contracts\ArrayableInterface interface.
返回一個可使用的響應最簡單的方式是直接從控制器返回數組或對象。不是每個對象都能夠被返回正確的格式，但因此，你應該確定它繼承了ArrayObject或者Illuminate\Support\Contracts\ArrayableInterface接口。
class UserController { public function index() { return User::all(); } }
在這個實例中，我們的User類繼承了Illuminate\Database\Eloquent\Model，意味著它能作為一個格式化的數組返回，所以我們能通過調用User::all(),簡單的返回一個users集合。
同樣的，你也能使用它返回一個單一的user。例：如下
class UserController { public function show($id) { return User::findOrFail($id); } }
這個包，將自動格式化響應信息之後作為JSON格式返回，並且為Content-Type 頭設置為application/json。
Response Builder 響應構建器
這個響應構建器，提供一個流暢的接口去簡單的生成一個定制的響應信息。這個響應構建器通常與transformers結合使用。
要想在你的控制器，使用這個響應返回。你應該引入（使用） Dingo\Api\Routing\Helpers。為了讓你的全部控制器都可以用使用這個特性，你應該創建一個基類控制器，讓你所有的控制器都去繼承（extends）它。
use Dingo\Api\Routing\Helpers; use Illuminate\Routing\Controller; class BaseController extends Controller { use Helpers; }
現在，你的控制器能簡單的繼承基本控制器。在你的控制器中可以經由$response屬性來訪問響應構建器。
關於這，更詳細的文檔，你應該看Transformers那節。（接下來，我會慢慢翻譯的，等。。）
Responding With An Array 作為一個數組返回
class UserController extends BaseController { public function show($id) { $user = User::findOrFail($id); return $this->response->array($user->toArray()); } }
Responding With A Single Item 作為一個item返回
class UserController extends BaseController { public function show($id) { $user = User::findOrFail($id); return $this->response->item($user, new UserTransformer); } }
Responding With A Collection Of Items 作為一個元素集合返回
class UserController extends BaseController
{
public function index()
{
$users = User::all();
return $this->response->collection($users, new UserTransformer);
}
}
Responding With Paginated Items 返回帶分頁的數組
class UserController extends BaseController { public function index() { $users = User::paginate(25); return $this->response->paginator($users, new UserTransformer); } }
Responding With No Content 無內容響應
return $this->response->noContent();
Responding With Created Response 創建了資源的響應
return $this->response->created();
你也可以，為這個created 隨意的提供一個值，作為第一個參數。
return $this->response->created($location);
Responding With An Error 返回一個錯誤提示
這個包內有很多不同的響應錯誤的提示，你可以快速的形成一個錯誤提示。（這塊文字理解，我感覺不太好，就把真實的返回值寫出來了）
return $this->response->error(‘This is an error.‘, 404);
返回信息：{"message":"This is an error.","status_code":404}
return $this->response->errorNotFound();
返回信息：{"message":"Not Found","status_code":404}
return $this->response->errorBadRequest();
返回信息：{"message":"Bad Request","status_code":400}
return $this->response->errorForbidden();
返回信息：{"message":"Forbidden","status_code":403}
return $this->response->errorInternal();
返回信息：{"message":"Internal Error","status_code":500}
return $this->response->errorUnauthorized();
返回信息：{"message":"Unauthorized","status_code":401}
Adding Additional Headers 添加附加的表頭
一旦您使用了上述方法中的一個，您就可以通過添加附加的表頭來進一步定制響應。
return $this->response->item($user, new UserTransformer)->withHeader(‘X-Foo‘, ‘Bar‘);
Adding Meta Data 添加元數據
某些轉化層可能會使用元數據（meta data）。當你需要提供與資源相關的額外數據時，這很有用。
return $this->response->item($user, new UserTransformer)->addMeta(‘foo‘, ‘bar‘);
你也可以設置一個 meta 數據的數組，省得多次調用 addMeta 方法。
return $this->response->item($user, new UserTransformer)->setMeta($meta);
Setting Response Status Code 設置返回值狀態
return $this->response->item($user, new UserTransformer)->setStatusCode(200);
Custom Response Formats 自定義響應格式
在這個配置章節，我們簡單的講解了返回信息格式。通過這個dingo包，我們將自動的使用json格式，並設置一個恰當的Content-Type頭。除了 JSON 格式化，還有一個 JSONP 格式化。這個 formatter 將會用一個回調包裹響應。更改格式只需要簡單將配置文件（Laravel）或啟動文件（Lumen）中的默認JSON格式替換成JSONP即可：
‘formats‘ => [ ‘json‘ => ‘Dingo\Api\Http\Response\Format\Jsonp‘ ]
或
Dingo\Api\Http\Response::addFormatter(‘json‘, new Dingo\Api\Http\Response\Format\Jsonp);
你可以註冊之後使用你自己需要的格式。你的格式應該繼承 Dingo\Api\Http\Response\Format\Format。這有很多請求應該被定義：formatEloquentModel，formatEloquentCollection，formatArray和getContentType。
Morphing And Morphed Events
在發送一個響應之前，它會改變它，在發送。這個過程包括運行所有轉換器（Transformer）以及通過配置的響應格式發送響應。如果你需要對響應的變化有更多的控制，你可以使用 ResponseWasMorphed 和 ResponseIsMorphing 這兩個事件.
在你的app/Listeners文件夾，創建一個監聽器。
use Dingo\Api\Event\ResponseWasMorphed;
class AddPaginationLinksToResponse
{
public function handle(ResponseWasMorphed $event)
{
if (isset($event->content[‘meta‘][‘pagination‘])) {
$links = $event->content[‘meta‘][‘pagination‘][‘links‘];
$event->response->headers->set(
‘link‘,
sprintf(‘<%s>; rel="next", <%s>; rel="prev"‘, $links[‘links‘][‘next‘], $links[‘links‘][‘previous‘])
);
}
}
}
然後通過在EventServiceProvider中註冊事件及其對應監聽器來監聽該事件：
protected $listen = [ ‘Dingo\Api\Event\ResponseWasMorphed‘ => [ ‘App\Listeners\AddPaginationLinksToResponse‘ ] ];
Now all responses that contain pagination links will also add these links to the Link header.(這句話，留給你們翻譯)
這章結束了，馬上要2018年了。新的一年，go go go !!!
第四節：dingo/API 最新版 V2.0 之 Responses （連載）