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 的构建。

学院君 has written 980 articles

Laravel学院院长,终身学习者

积分:112767 等级:P12 职业:手艺人 城市:杭州

5 条回复

  1. 学习者 学习者 says:
    ‘comments’ => ArticleCommentsResource::collection($this->comments),解决问题,在上面的文档才是正确的,这个教程不准确!
  2. 学习者 学习者 says:
    'comments' => new ArticleCommentsResource($this->comments),做到这一步,报错,Property [id] does not exist on this collection instance.,然后我就写成'comments' => $this->comments就可以,请问是哪里错了
  3. xtn xtn says:
    感谢学院君 非常好的教程 还有后续的api的教程吗?

登录后才能进行评论,立即登录?