使用 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\TaskControllershow 方法为例进行演示,编写 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,可以查看注册的资源路由:

Dingo API 资源路由

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

Dingo API JSON 响应

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

上一篇: 使用 Dingo API 快速构建 RESTful API(二)—— 编写第一个 API 接口

下一篇: 使用 Dingo API 快速构建 RESTful API(四)—— 转化器篇(上):Fractal 简介及其使用入门