Laravel API 系列教程（三）：使用 API Resource 来创建自己的 {JSON:API} 格式 API

上一篇教程中我们通过 jwt-auth 实现了 Laravel 的 API 认证，认证过后就可以通过 http://apidemo.test/api/auth/user 接口访问当前用户信息：

可以看到上面的返回数据以原生格式返回，没有经过任何处理，甚至有可能包含敏感信息，我们当然可以处理之后再返回，一个两个接口还好，如果现实业务中面对成百上千个接口呢？这种处理方式显然不合适，不仅耗费大量时间和精力，复用性差，且难以维护。好在 Laravel 5.5 开始，内置了 API Resource 功能帮助我们快速建立起模型和 JSON 返回数据之间的桥梁，在此之前，很多人是通过第三方扩展包基于 Fractal 实现数据格式转化的，API Resource 有点类似把 Fractal 扩展包收编为官方特性的味道，为了更好的引入 API Resource，我们先来看看 Fractal 怎么用：

Laravel Fractal 扩展包

首先通过 Composer 安装对应扩展包：

composer require spatie/laravel-fractal

安装完成后，发布配置文件以便定制 Fractal：

php artisan vendor:publish --provider="Spatie\Fractal\FractalServiceProvider"

还是以 User 模型为例，我们为它创建一个格式转化器：

php artisan make:transformer UserTransformer

编辑生成的 app/Transformers/UserTransformer 文件内容如下：

namespace App\Transformers;

use App\User;
use League\Fractal\TransformerAbstract;

class UserTransformer extends TransformerAbstract
{
    /**
     * A Fractal transformer.
     * @param User $user
     * @return array
     */
    public function transform(User $user)
    {
        return [
            'id' => $user->id,
            'name' => $user->name,
            'email' => $user->email
        ];
    }
}

接下来通过 Fractal 替换 AuthController 控制器的 user() 方法实现：

    public function user(Request $request)
    {
        $user = User::find(Auth::user()->id);
        $user = fractal($user, new UserTransformer())->toArray();
        return response()->json($user);
    }

当我们再次访问 http://apidemo.test/api/user/auth 接口的话，会返回经过转化的数据格式：

或者使用 respond() 方法简化代码：

$user = User::find(Auth::user()->id);
$user = fractal($user, new UserTransformer())->toArray();
return response()->json($user);

返回结果和上面一致。

我们还可以添加响应状态码和响应头到响应：

return fractal($user, new UserTransformer())->respond(200, [
    'a-header' => 'a value',
    'another-header' => 'another value',
]);

甚至通过回调完成更复杂功能：

return fractal($user, new UserTransformer())->respond(function(JsonResponse $response) {
        $response
            ->setStatusCode(200)
            ->header('a-header', 'a value')
            ->withHeaders([
                'another-header' => 'another value',
                'yet-another-header' => 'yet another value',
            ]);
    });

以上就是 Laravel Fractal 扩展包的一个基本使用，更多使用方法可查看其 Github 项目。Laravel 5.5 新增的 API Resource 功能与上述实现思路基本一致，不过由于有官方加持，所以与 Laravel Eloquent 模型的各种功能结合可能更加紧密。下面就一起来看看吧：

API Resource

在使用 API Resource 之前，访问 http://apidemo.test/api/articles/1 接口，返回的数据格式如下：

同样也就是原生数据。下面我们通过如下 Artisan 命令来创建一个资源转化器：

php artisan make:resource ArticleResource

生成的文件位于 app\Http\Resources 目录下，编辑 ArticleResource 类代码如下：

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\Resource;

class ArticleResource extends Resource
{
    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return [
            'type' => 'article',
            'id'   => (string)$this->id,
            'attributes' => [
                'title' => $this->title,
                'content' => $this->body,
            ],
        ];
    }
}

然后修改 ArticleController 控制器的 show() 方法实现：

public function show(Article $article)
{
    return new ArticleResource($article);
}

再次访问 http://apidemo.test/api/articles/1 接口，数据返回格式如下：

兼容 JSON:API

默认数据结构被包裹到 data 里面，如果你不想有这个数据结构，可以通过下面的代码去除：

public function show(Article $article)
{
    ArticleResource::withoutWrapping();
    return new ArticleResource($article);
}

这样返回的数据格式如下：

额外信息

有时候你想要获取数据库记录以外的其他相关数据，如分页信息或者页面 URL，可以在 ArticleResource 控制器中新增 with 方法来实现：

public function with($request)
{
    return [
        'links'    => [
            'self' => url('api/articles/' . $this->id),
        ],
    ];
}

这样访问文章接口返回数据如下：

关联关系

除此之外，返回与文章模型关联的其他模型数据如评论、作者信息等也是很常见的需求，API Resource 也可以对此提供良好的支持。

为了演示此功能，首先我们创建一个 Comment 评论模型类：

php artisan make:model Comment -m

编辑生成的迁移文件类 CreateCommentsTable 的 up 方法：

public function up()
{
    Schema::create('comments', function (Blueprint $table) {
        $table->increments('id');
        $table->integer('post_id');
        $table->integer('user_id');
        $table->string('content');
        $table->tinyInteger('status');
        $table->timestamps();
    });
}

然后运行如下命令将变更同步到数据库：

php artisan migrate

再生成一个填充器类为数据表 comments 填充一些测试数据：

php artisan make:seeder CommentsTableSeeder

编辑生成的 CommentsTableSeeder 类代码：

<?php
use Illuminate\Database\Seeder;

use App\Comment;

class CommentsTableSeeder extends Seeder
{
    /**
     * Run the database seeds.
     *
     * @return void
     */
    public function run()
    {
        // Let's truncate our existing records to start from scratch.
        Comment::truncate();

        $faker = \Faker\Factory::create();

        // And now, let's create a few articles in our database:
        for ($i = 0; $i < 100; $i++) {
            Comment::create([
                'post_id' => random_int(1, 50),
                'user_id' => random_int(1, 14),
                'status' => random_int(0, 1),
                'content' => $faker->sentence,
            ]);
        }
    }
}

运行以下 Artisan 命令将测试数据插入数据表：

php artisan db:seed --class=CommentsTableSeeder

在 App\Article 模型类中定义关联关系：

public function comments()
{
    return $this->hasMany(Comment::class, 'post_id', 'id');
}

为这个关联关系创建资源转化器：

php artisan make:resource --collection ArticleCommentsResource

然后修改 ArticleResource 类的 toArray() 方法：

public function toArray($request)
{
    return [
        'type' => 'article',
        'id'   => (string)$this->id,
        'attributes' => [
            'title' => $this->title,
            'content' => $this->body,
        ],
        'comments' => new ArticleCommentsResource($this->comments),
    ];
}

这样，再次访问 http://apidemo.test/api/articles/1 接口，返回数据格式如下：

如果想要自定义 comments 的返回字段可以去修改 ArticleCommentsResource 类。

API Resource 最大的优点是解耦了数据格式与业务代码的耦合，提高了代码的复用性和可维护性，更多功能可以参考官方文档，这些都只是带你入门，更多功能的使用和发掘，有赖你在实践中去探寻。

以上三篇都是围绕功能角度讲 API，下一篇我们将围绕限流、开关降级以及性能优化等角度来阐述 API 的构建。