使用 Dingo API 快速构建 RESTful API（三）—— 返回基本 JSON 响应

API 的核心功能就是获取请求并返回响应给客户端，响应的数据格式是多样的，比如 JSON、XML、HTML，目前比较通用的是返回 JSON 格式数据，返回响应的方式也是多样的，这取决于当前构建的 API 的复杂度以及对未来的考量。

快速入门

要返回 JSON 格式响应，最简单的方式是直接从控制器返回数组或对象，但不是每个响应对象都能保证格式正确，所以你要确保它们实现了 ArrayObject 或者 Illuminate\Contracts\Support\Arrayable 接口：

class TaskController extends Controller
{
    public function index()
    {
        return Task::all();
    }
}

在本例中，Task 类继承自 Illuminate\Database\Eloquent\Model，这意味着返回的是可以被格式化为数组的数据，当然也可以返回单个用户：

class TaskController extends Controller
{
    public function show($id)
    {
        return Task::findOrFail($id);
    }
}

对于以上返回的数组或对象，Dingo API 会自动将响应数据格式化为 JSON 格式并设置 Content-Type 响应头为 application/json。

响应构建器

当然，如果仅限于此的话，在 Dingo 中返回响应与 Laravel 框架自带的功能并无二致。实际上，在 Dingo API 中，我们可以通过 Dingo 扩展包提供的响应构建器构建各种不同形式的响应，如果与转换器（Transformer）相结合的话，还可以对响应数据按照需要进行格式化，从而极大提高 API 响应构建的灵活性和可扩展性，关于转换器我们将在下一篇教程去讨论，这篇教程我们重点关注响应构建器，并且通过响应构建器来返回一个最基本的 JSON 响应。

要使用响应构建器，控制器需要引用 Dingo\Api\Routing\Helpers trait，为了让每个 Dingo API 控制器都可以使用这个 trait，我们将其放置在 API 基类控制器 ApiController 中（在 app/Http/Controllers 创建这个新的 API 基类控制器）：

<?php

namespace App\Http\Controllers;

use Dingo\Api\Routing\Helpers;

class ApiController extends Controller
{
    use Helpers;
}

现在可以定义一个继承自该控制器的子控制器，为了与之前项目中已存在的 TaskController 区分开，我们单独创建一个新的资源控制器，并将其存放到 app/Http/Controllers/Api 目录下：

php artisan make:controller Api/TaskController --resource

修改该控制器，使其继承自上面创建的 ApiController 基类。在子控制器中可以通过 $this->response 属性即可访问 Dingo API 响应构建器实例，下面我们将通过这个响应构建器来构建返回给客户端的 JSON 响应。

基本 JSON 响应

要在 Dingo 中返回 JSON 响应，最简单的方式就是在响应构建器上调用 array 方法，我们以 Api\TaskController 的 show 方法为例进行演示，编写 show 方法实现代码如下：

<?php
namespace App\Http\Controllers\Api;

use App\Http\Controllers\ApiController;
use App\Task;
use Illuminate\Http\Request;   

class TaskController extends ApiController
{
    ... 
    public function show($id)
    {
        $task = Task::findOrFail($id);
        return $this->response->array($task->toArray());
    }
    ...
}

这种调用方式和直接返回 $task 实例一样，底层都会转化为实例化 Illuminate\Http\Response 并将响应数据格式化为 JSON 数据。

接下来，在 routes/api.php 中新增一个 Dingo API Endpoint，这次，我们定义一个 tasks 资源路由，并将其版本号设置为 v3：

$api->version('v3', function ($api) {
    $api->resource('tasks', \App\Http\Controllers\Api\TaskController::class);
});

通过 php artisan api:routes，可以查看注册的资源路由：

这样一来，就可以通过 Postman 访问刚刚定义的 tasks.show 路由，返回响应数据如下：

至此，我们就通过 Dingo 响应构建器返回了一个最基本的 JSON 响应，当然，这只是响应构建器一个最基本的应用，等到我们下一篇介绍完 Dingo 提供的转化器后，我们将结合响应构建器和格式转换器构建一些更复杂的 API 响应。