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

我们通过 Article 模型类来演示 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
编辑生成的迁移文件类 CreateCommentsTableup 方法:
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 类代码:
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 的构建。

上一篇: Laravel API 系列教程(二): 结合 Laravel 5.5 和 Vue SPA 基于 jwt-auth 实现 API 认证

下一篇: Laravel API 系列教程(四):基于 GraphQL 构建 Laravel API —— 基本使用篇