API 资源

13.x

13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 13 中文文档 /

本文档最新版为 12.x，旧版本可能放弃维护，推荐阅读最新版！

Eloquent: API 资源

介绍
生成资源
概念概述
- 资源集合
编写资源
JSON:API 资源
资源响应

介绍

构建 API 时，你可能需要在 Eloquent 模型与实际返回给应用用户的 JSON 响应之间设置一个转换层。例如，你可能希望仅向部分用户显示某些属性，或始终在模型的 JSON 表示中包含某些关联。Eloquent 资源类让你能够以简洁、直观的方式，将模型及模型集合转换为 JSON。

当然，你始终可以使用 Eloquent 模型或集合的 toJson 方法将它们转换为 JSON；不过，Eloquent 资源能让你更精细、更灵活地控制模型及其关联的 JSON 序列化。

生成资源

你可以使用 make:resource Artisan 命令生成资源类。默认情况下，资源会放在应用的 app/Http/Resources 目录中。资源类继承自 Illuminate\Http\Resources\Json\JsonResource 类：

php artisan make:resource UserResource

资源集合

除了生成转换单个模型的资源外，你还可以生成负责转换模型集合的资源。这让 JSON 响应能够包含与整个资源集合相关的链接及其他元信息。

要创建资源集合，可以在生成资源时使用 --collection 选项。或者，在资源名称中包含 Collection，也会让 Laravel 创建资源集合。资源集合继承自 Illuminate\Http\Resources\Json\ResourceCollection 类：

php artisan make:resource User --collection

php artisan make:resource UserCollection

概念概述

[!NOTE]
这里概括介绍资源和资源集合。强烈建议你继续阅读本文的其他章节，以深入了解资源提供的自定义能力和各项功能。

在深入探讨编写资源时的所有可用选项之前，我们先从整体上了解资源在 Laravel 中的使用方式。资源类表示需要转换为 JSON 结构的单个模型。例如，下面是一个简单的 UserResource 资源类：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * 将资源转换为数组。
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

每个资源类都定义了一个 toArray 方法，返回一个属性数组。当资源作为路由或控制器方法的响应返回时，这些属性会被转换为 JSON。

注意，我们可以直接通过 $this 变量访问模型属性。这是因为资源类会自动将属性和方法的访问代理到底层模型，方便你使用。定义好资源后，就可以从路由或控制器返回它。资源通过构造函数接收底层模型实例：

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/user/{id}', function (string $id) {
    return new UserResource(User::findOrFail($id));
});

为方便起见，你可以使用模型的 toResource 方法，它会遵循框架约定，自动查找模型对应的资源：

return User::findOrFail($id)->toResource();

调用 toResource 方法时，Laravel 会在最接近模型命名空间的 Http\Resources 命名空间中，尝试查找与模型同名、可选地以 Resource 为后缀的资源。

如果资源类不遵循这一命名约定，或位于其他命名空间，你可以使用 UseResource 特性指定模型的默认资源：

<?php

namespace App\Models;

use App\Http\Resources\CustomUserResource;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Attributes\UseResource;

#[UseResource(CustomUserResource::class)]
class User extends Model
{
    // ...
}

你也可以将资源类传给 toResource 方法来指定资源类：

return User::findOrFail($id)->toResource(CustomUserResource::class);

资源集合

如果要返回资源集合或分页响应，你应该在路由或控制器中创建资源实例时，使用资源类提供的 collection 方法：

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/users', function () {
    return UserResource::collection(User::all());
});

或者，为方便起见，你可以使用 Eloquent 集合的 toResourceCollection 方法，它会遵循框架约定，自动查找模型对应的资源集合：

return User::all()->toResourceCollection();

调用 toResourceCollection 方法时，Laravel 会在最接近模型命名空间的 Http\Resources 命名空间中，尝试查找与模型同名、以 Collection 为后缀的资源集合。

如果资源集合类不遵循这一命名约定，或位于其他命名空间，你可以使用 UseResourceCollection 特性指定模型的默认资源集合：

<?php

namespace App\Models;

use App\Http\Resources\CustomUserCollection;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Attributes\UseResourceCollection;

#[UseResourceCollection(CustomUserCollection::class)]
class User extends Model
{
    // ...
}

你也可以将资源集合类传给 toResourceCollection 方法来指定资源集合类：

return User::all()->toResourceCollection(CustomUserCollection::class);

自定义资源集合

默认情况下，资源集合不允许添加需要随集合一同返回的自定义元数据。如果你想自定义资源集合响应，可以创建一个专门的资源来表示该集合：

php artisan make:resource UserCollection

生成资源集合类后，你就可以轻松定义响应中应包含的元数据：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * 将资源集合转换为数组。
     *
     * @return array<int|string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }
}

定义好资源集合后，就可以从路由或控制器返回它：

use App\Http\Resources\UserCollection;
use App\Models\User;

Route::get('/users', function () {
    return new UserCollection(User::all());
});

或者，为方便起见，你可以使用 Eloquent 集合的 toResourceCollection 方法，它会遵循框架约定，自动查找模型对应的资源集合：

return User::all()->toResourceCollection();

调用 toResourceCollection 方法时，Laravel 会在最接近模型命名空间的 Http\Resources 命名空间中，尝试查找与模型同名、以 Collection 为后缀的资源集合。

保留集合键

从路由返回资源集合时，Laravel 会重置集合的键，使其按数字顺序排列。不过，你可以在资源类上使用 PreserveKeys 特性，指示应保留集合的原始键：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Attributes\PreserveKeys;
use Illuminate\Http\Resources\Json\JsonResource;

#[PreserveKeys]
class UserResource extends JsonResource
{
    // ...
}

当 preserveKeys 属性设置为 true 时，从路由或控制器返回集合时，集合的键将被保留：

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/users', function () {
    return UserResource::collection(User::all()->keyBy->id);
});

自定义底层资源类

通常，资源集合的 $this->collection 属性会自动填充为将集合中每一项映射到其单个资源类后的结果。单个资源类的名称默认为集合类名去掉末尾的 Collection 部分。此外，你可以根据个人偏好，为单个资源类添加或省略 Resource 后缀。

例如，UserCollection 会尝试将给定的用户实例映射为 UserResource 资源。要自定义这一行为，可以在资源集合上使用 Collects 特性：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Attributes\Collects;
use Illuminate\Http\Resources\Json\ResourceCollection;

#[Collects(Member::class)]
class UserCollection extends ResourceCollection
{
    // ...
}

编写资源

[!NOTE]
如果你尚未阅读概念概述，强烈建议先阅读该部分，再继续阅读本文。

资源只需将给定模型转换为数组。因此，每个资源都包含一个 toArray 方法，将模型属性转换为适合 API 的数组，以便从应用的路由或控制器返回：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * 将资源转换为数组。
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

定义好资源后，就可以直接从路由或控制器返回它：

use App\Models\User;

Route::get('/user/{id}', function (string $id) {
    return User::findOrFail($id)->toResource();
});

关联

如果希望在响应中包含关联资源，可以将它们添加到资源的 toArray 方法返回的数组中。在本例中，我们会使用 PostResource 资源的 collection 方法，将用户的博客文章添加到资源响应中：

use App\Http\Resources\PostResource;
use Illuminate\Http\Request;

/**
 * 将资源转换为数组。
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'posts' => PostResource::collection($this->posts),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

[!NOTE]
如果你希望仅在关联已加载时才包含它们，请参阅条件关联文档。

资源集合

资源将单个模型转换为数组，而资源集合将模型集合转换为数组。不过，你并不一定要为每个模型都定义资源集合类，因为所有 Eloquent 模型集合都提供了 toResourceCollection 方法，可以即时生成一个临时资源集合：

use App\Models\User;

Route::get('/users', function () {
    return User::all()->toResourceCollection();
});

不过，如果需要自定义随集合返回的元数据，就必须定义自己的资源集合：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * 将资源集合转换为数组。
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }
}

与单个资源一样，资源集合也可以直接从路由或控制器返回：

use App\Http\Resources\UserCollection;
use App\Models\User;

Route::get('/users', function () {
    return new UserCollection(User::all());
});

或者，为方便起见，你可以使用 Eloquent 集合的 toResourceCollection 方法，它会遵循框架约定，自动查找模型对应的资源集合：

return User::all()->toResourceCollection();

调用 toResourceCollection 方法时，Laravel 会在最接近模型命名空间的 Http\Resources 命名空间中，尝试查找与模型同名、以 Collection 为后缀的资源集合。

数据包裹

默认情况下，将资源响应转换为 JSON 时，最外层资源会被包裹在 data 键中。例如，典型的资源集合响应如下：

{
    "data": [
        {
            "id": 1,
            "name": "Eladio Schroeder Sr.",
            "email": "therese28@example.com"
        },
        {
            "id": 2,
            "name": "Liliana Mayert",
            "email": "evandervort@example.com"
        }
    ]
}

如果想禁用最外层资源的数据包裹，你应该在基类 Illuminate\Http\Resources\Json\JsonResource 上调用 withoutWrapping 方法。通常，你应该在 AppServiceProvider 或应用每次请求都会加载的其他服务提供者中调用该方法：

<?php

namespace App\Providers;

use Illuminate\Http\Resources\Json\JsonResource;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 注册应用服务。
     */
    public function register(): void
    {
        // ...
    }

    /**
     * 引导应用服务。
     */
    public function boot(): void
    {
        JsonResource::withoutWrapping();
    }
}

[!WARNING]
withoutWrapping 方法只影响最外层响应，不会移除你在自定义资源集合中手动添加的 data 键。

包裹嵌套资源

你可以自由决定资源关联的数据包裹方式。如果希望所有资源集合无论嵌套层级如何，都被包裹在 data 键中，你应该为每个资源定义资源集合类，并将集合放在 data 键中返回。

你可能会担心，这是否会让最外层资源被包裹在两层 data 键中。不必担心，Laravel 绝不会让资源被意外地重复包裹，因此你无需考虑正在转换的资源集合的嵌套层级：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class CommentsCollection extends ResourceCollection
{
    /**
     * 将资源集合转换为数组。
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return ['data' => $this->collection];
    }
}

数据包裹与分页

通过资源响应返回分页集合时，即使已经调用了 withoutWrapping 方法，Laravel 仍会将资源数据包裹在 data 键中。这是因为分页响应始终包含 meta 和 links 键，用于提供分页器的状态信息：

{
    "data": [
        {
            "id": 1,
            "name": "Eladio Schroeder Sr.",
            "email": "therese28@example.com"
        },
        {
            "id": 2,
            "name": "Liliana Mayert",
            "email": "evandervort@example.com"
        }
    ],
    "links":{
        "first": "http://example.com/users?page=1",
        "last": "http://example.com/users?page=1",
        "prev": null,
        "next": null
    },
    "meta":{
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://example.com/users",
        "per_page": 15,
        "to": 10,
        "total": 10
    }
}

分页

你可以将 Laravel 分页器实例传给资源的 collection 方法，或传给自定义资源集合：

use App\Http\Resources\UserCollection;
use App\Models\User;

Route::get('/users', function () {
    return new UserCollection(User::paginate());
});

或者，为方便起见，你可以使用分页器的 toResourceCollection 方法，它会遵循框架约定，自动查找分页模型对应的资源集合：

return User::paginate()->toResourceCollection();

分页响应始终包含 meta 和 links 键，用于提供分页器的状态信息：

{
    "data": [
        {
            "id": 1,
            "name": "Eladio Schroeder Sr.",
            "email": "therese28@example.com"
        },
        {
            "id": 2,
            "name": "Liliana Mayert",
            "email": "evandervort@example.com"
        }
    ],
    "links":{
        "first": "http://example.com/users?page=1",
        "last": "http://example.com/users?page=1",
        "prev": null,
        "next": null
    },
    "meta":{
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://example.com/users",
        "per_page": 15,
        "to": 10,
        "total": 10
    }
}

自定义分页信息

如果想自定义分页响应的 links 或 meta 键中的信息，你可以在资源上定义 paginationInformation 方法。该方法会接收 $paginated 数据和默认信息数组 $default，后者是一个包含 links 和 meta 键的数组：

/**
 * 自定义资源的分页信息。
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  array  $paginated
 * @param  array  $default
 * @return array
 */
public function paginationInformation($request, $paginated, $default)
{
    $default['links']['custom'] = 'https://example.com';

    return $default;
}

条件属性

有时，你可能希望仅在满足给定条件时，才将某个属性包含在资源响应中。例如，你可能希望仅在当前用户是「管理员」时才包含某个值。Laravel 提供了多种辅助方法来处理这类情况。你可以使用 when 方法，有条件地将属性添加到资源响应中：

/**
 * 将资源转换为数组。
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'secret' => $this->when($request->user()->isAdmin(), 'secret-value'),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

在本例中，只有当已认证用户的 isAdmin 方法返回 true 时，secret 键才会出现在最终的资源响应中。如果该方法返回 false，secret 键就会在资源响应发送给客户端之前被移除。when 方法让你能够简洁地定义资源，而无需在构建数组时使用条件语句。

when 方法还接受闭包作为第二个参数，这样只有当给定条件为 true 时，才会计算结果值：

'secret' => $this->when($request->user()->isAdmin(), function () {
    return 'secret-value';
}),

whenHas 方法可以在底层模型确实存在某个属性时，才包含该属性：

'name' => $this->whenHas('name'),

此外，whenNotNull 方法可以在属性不为 null 时，才将该属性包含在资源响应中：

'name' => $this->whenNotNull($this->name),

合并条件属性

有时，你可能希望多个属性都仅在同一个条件满足时才包含在资源响应中。这时，可以使用 mergeWhen 方法，仅在给定条件为 true 时，才将这些属性包含在响应中：

/**
 * 将资源转换为数组。
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        $this->mergeWhen($request->user()->isAdmin(), [
            'first-secret' => 'value',
            'second-secret' => 'value',
        ]),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

同样，如果给定条件为 false，这些属性就会在资源响应发送给客户端之前被移除。

[!WARNING]
mergeWhen 方法不应在混用字符串键和数字键的数组中使用，也不应在数字键未按顺序排列的数组中使用。

条件关联

除了有条件地加载属性外，你还可以根据模型是否已加载某个关联，有条件地将该关联包含在资源响应中。这样，控制器就能决定要在模型上加载哪些关联，而资源则可以轻松地仅包含已经加载的关联。这有助于在资源中避免「N+1」查询问题。

whenLoaded 方法可用于有条件地加载关联。为避免不必要的关联加载，该方法接受关联名称，而不是关联本身：

use App\Http\Resources\PostResource;

/**
 * 将资源转换为数组。
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'posts' => PostResource::collection($this->whenLoaded('posts')),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

在本例中，如果关联尚未加载，posts 键就会在资源响应发送给客户端之前被移除。

条件关联数量

除了有条件地包含关联外，你还可以根据模型是否已加载关联数量，有条件地将关联「数量」包含在资源响应中：

new UserResource($user->loadCount('posts'));

whenCounted 方法可以有条件地将关联数量包含在资源响应中。如果关联数量不存在，该方法会避免将这一属性包含在响应中：

/**
 * 将资源转换为数组。
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'posts_count' => $this->whenCounted('posts'),
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

在本例中，如果尚未加载 posts 关联的数量，posts_count 键就会在资源响应发送给客户端之前被移除。

其他类型的聚合结果，如 avg、sum、min 和 max，也可以通过 whenAggregated 方法有条件地加载：

'words_avg' => $this->whenAggregated('posts', 'words', 'avg'),
'words_sum' => $this->whenAggregated('posts', 'words', 'sum'),
'words_min' => $this->whenAggregated('posts', 'words', 'min'),
'words_max' => $this->whenAggregated('posts', 'words', 'max'),

条件中间表信息

除了有条件地在资源响应中包含关联信息外，你还可以使用 whenPivotLoaded 方法，有条件地包含多对多关联中间表的数据。whenPivotLoaded 方法的第一个参数是中间表名称。第二个参数应该是一个闭包，用于在模型上存在中间表信息时，返回需要包含的值：

/**
 * 将资源转换为数组。
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'expires_at' => $this->whenPivotLoaded('role_user', function () {
            return $this->pivot->expires_at;
        }),
    ];
}

如果关联使用了自定义中间表模型，你可以将中间表模型实例作为第一个参数传给 whenPivotLoaded 方法：

'expires_at' => $this->whenPivotLoaded(new Membership, function () {
    return $this->pivot->expires_at;
}),

如果中间表使用了 pivot 以外的访问器，你可以使用 whenPivotLoadedAs 方法：

/**
 * 将资源转换为数组。
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'expires_at' => $this->whenPivotLoadedAs('subscription', 'role_user', function () {
            return $this->subscription->expires_at;
        }),
    ];
}

添加元数据

某些 JSON API 标准要求在资源和资源集合响应中添加元数据。这通常包括指向资源或关联资源的 links，或关于资源本身的元数据。如果需要为资源返回附加元数据，可以将其包含在 toArray 方法中。例如，转换资源集合时，你可以包含 links 信息：

/**
 * 将资源转换为数组。
 *
 * @return array<string, mixed>
 */
public function toArray(Request $request): array
{
    return [
        'data' => $this->collection,
        'links' => [
            'self' => 'link-value',
        ],
    ];
}

从资源返回附加元数据时，你无需担心会意外覆盖 Laravel 在返回分页响应时自动添加的 links 或 meta 键。你定义的任何附加 links 都会与分页器提供的链接合并。

顶层元数据

有时，你可能希望仅在资源是所返回的最外层资源时，才包含某些元数据。这通常是关于整个响应的元信息。要定义这些元数据，可以向资源类添加 with 方法。该方法应该返回一个元数据数组，只有当资源是正在转换的最外层资源时，才会将这些元数据包含在资源响应中：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * 将资源集合转换为数组。
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return parent::toArray($request);
    }

    /**
     * 获取应随资源数组返回的附加数据。
     *
     * @return array<string, mixed>
     */
    public function with(Request $request): array
    {
        return [
            'meta' => [
                'key' => 'value',
            ],
        ];
    }
}

构建资源时添加元数据

你也可以在路由或控制器中构建资源实例时添加顶层数据。所有资源都提供了 additional 方法，它接受一个数据数组，将其中的数据添加到资源响应中：

return User::all()
    ->load('roles')
    ->toResourceCollection()
    ->additional(['meta' => [
        'key' => 'value',
    ]]);

JSON:API 资源

Laravel 内置了 JsonApiResource，这一资源类能生成符合 JSON:API 规范的响应。它继承自标准的 JsonResource 类，自动处理资源对象结构、关联、稀疏字段集、关联包含及属性的惰性求值，并将 Content-Type 响应头设置为 application/vnd.api+json。

[!NOTE]
Laravel 的 JSON:API 资源负责响应的序列化。如果你还需要解析传入的 JSON:API 查询参数，例如过滤和排序参数，Spatie 的 Laravel Query Builder 是很好的配套扩展包。

生成 JSON:API 资源

要生成 JSON:API 资源，可以使用 make:resource Artisan 命令并添加 --json-api 选项：

php artisan make:resource PostResource --json-api

生成的类会继承 Illuminate\Http\Resources\JsonApi\JsonApiResource，并包含供你定义的 $attributes 和 $relationships 属性：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\JsonApi\JsonApiResource;

class PostResource extends JsonApiResource
{
    /**
     * 资源的属性。
     */
    public $attributes = [
        // ...
    ];

    /**
     * 资源的关联。
     */
    public $relationships = [
        // ...
    ];
}

JSON:API 资源可以像标准资源一样，从路由和控制器返回：

use App\Http\Resources\PostResource;
use App\Models\Post;

Route::get('/api/posts/{post}', function (Post $post) {
    return new PostResource($post);
});

或者，为方便起见，你可以使用模型的 toResource 方法：

Route::get('/api/posts/{post}', function (Post $post) {
    return $post->toResource();
});

这会生成一个符合 JSON:API 规范的响应：

{
    "data": {
        "id": "1",
        "type": "posts",
        "attributes": {
            "title": "Hello World",
            "body": "This is my first post."
        }
    }
}

要返回 JSON:API 资源集合，可以使用 collection 方法或便捷方法 toResourceCollection：

return PostResource::collection(Post::all());

return Post::all()->toResourceCollection();

定义属性

你可以通过两种方式，定义 JSON:API 资源中应包含的属性。

最简单的方式是在资源上定义 $attributes 属性。你可以将属性名称列为数组的值，这些属性会直接从底层模型读取：

public $attributes = [
    'title',
    'body',
    'created_at',
];

如果某个属性的计算开销较大，你可以在 toAttributes 返回的数组中以闭包形式提供该属性，这样只有在响应确实需要它时才会求值。

或者，如果希望完全控制资源属性，你可以重写资源上的 toAttributes 方法：

/**
 * 获取资源的属性。
 *
 * @return array<string, mixed>
 */
public function toAttributes(Request $request): array
{
    return [
        'title' => $this->title,
        'body' => $this->body,
        'is_published' => fn () => $this->published_at !== null,
        'created_at' => $this->created_at,
        'updated_at' => $this->updated_at,
    ];
}

定义关联

JSON:API 资源支持定义符合 JSON:API 规范的关联。只有客户端通过 include 查询参数请求关联时，才会序列化这些关联。

`$relationships` 属性

你可以通过资源上的 $relationships 属性，定义允许包含的关联：

public $relationships = [
    'author',
    'comments',
];

将关联名称列为数组的值时，Laravel 会解析对应的 Eloquent 关联，并自动查找相应的资源类。如果需要显式指定资源类，可以使用键与类的对应关系来定义该关联：

use App\Http\Resources\UserResource;

public $relationships = [
    'author' => UserResource::class,
    'comments',
];

你也可以重写资源上的 toRelationships 方法：

/**
 * 获取资源的关联。
 */
public function toRelationships(Request $request): array
{
    return [
        'author' => UserResource::class,
        'comments' => fn () => CommentResource::collection(
            $request->user()->is($this->resource)
                ? $this->comments
                : $this->comments->where('is_public', true),
        ),
    ];
}

使用闭包能让你更灵活地控制关联数据，同时仍然只在客户端请求时才解析该关联。

包含关联

客户端可以使用 include 查询参数请求关联资源：

GET /api/posts/1?include=author,comments

生成的响应会在 relationships 键中包含资源标识符对象，并在顶层 included 数组中包含完整的资源对象：

{
    "data": {
        "id": "1",
        "type": "posts",
        "attributes": {
            "title": "Hello World"
        },
        "relationships": {
            "author": {
                "data": {
                    "id": "1",
                    "type": "users"
                }
            },
            "comments": {
                "data": [
                    {
                        "id": "1",
                        "type": "comments"
                    }
                ]
            }
        }
    },
    "included": [
        {
            "id": "1",
            "type": "users",
            "attributes": {
                "name": "Taylor Otwell"
            }
        },
        {
            "id": "1",
            "type": "comments",
            "attributes": {
                "body": "Great post!"
            }
        }
    ]
}

可以使用点表示法包含嵌套关联：

GET /api/posts/1?include=comments.author

关联深度

默认情况下，包含嵌套关联时会受到最大深度的限制。你可以使用 maxRelationshipDepth 方法自定义这一限制，通常在应用的某个服务提供者中调用：

use Illuminate\Http\Resources\JsonApi\JsonApiResource;

JsonApiResource::maxRelationshipDepth(3);

资源类型与 ID

默认情况下，资源的 type 由资源类名推导而来。例如，PostResource 生成的类型为 posts，BlogPostResource 生成的类型为 blog_posts。资源的 id 则从模型的主键解析而来。

如果需要自定义这些值，你可以重写资源上的 toType 和 toId 方法：

/**
 * 获取资源的类型。
 */
public function toType(Request $request): string
{
    return 'articles';
}

/**
 * 获取资源的 ID。
 */
public function toId(Request $request): string
{
    return (string) $this->uuid;
}

当资源类型需要与其类名不同时，这尤其有用。例如，AuthorResource 包裹的是 User 模型，但应输出 authors 类型。

稀疏字段集与关联包含

JSON:API 资源支持稀疏字段集，允许客户端使用 fields 查询参数，为每种资源类型只请求特定的属性：

GET /api/posts?fields[posts]=title,created_at&fields[users]=name

这样，posts 资源中只会包含 title 和 created_at 属性，users 资源中只会包含 name 属性。

忽略查询字符串

如果希望为某个资源响应禁用稀疏字段集过滤，你可以调用 ignoreFieldsAndIncludesInQueryString 方法：

return $post->toResource()
    ->ignoreFieldsAndIncludesInQueryString();

包含之前已加载的关联

默认情况下，只有通过 include 查询参数请求关联时，响应中才会包含该关联。如果希望忽略查询字符串，包含所有之前已预加载的关联，你可以调用 includePreviouslyLoadedRelationships 方法：

return $post->load('author', 'comments')
    ->toResource()
    ->includePreviouslyLoadedRelationships();

链接与元数据

你可以通过重写资源上的 toLinks 和 toMeta 方法，为 JSON:API 资源对象添加链接与元信息：

/**
 * 获取资源的链接。
 */
public function toLinks(Request $request): array
{
    return [
        'self' => route('api.posts.show', $this->resource),
    ];
}

/**
 * 获取资源的元信息。
 */
public function toMeta(Request $request): array
{
    return [
        'readable_created_at' => $this->created_at->diffForHumans(),
    ];
}

这会在响应的资源对象中添加 links 和 meta 键：

{
    "data": {
        "id": "1",
        "type": "posts",
        "attributes": {
            "title": "Hello World"
        },
        "links": {
            "self": "https://example.com/api/posts/1"
        },
        "meta": {
            "readable_created_at": "2 hours ago"
        }
    }
}

资源响应

如前所述，资源可以直接从路由和控制器返回：

use App\Models\User;

Route::get('/user/{id}', function (string $id) {
    return User::findOrFail($id)->toResource();
});

不过，有时你可能需要在响应发送给客户端之前，自定义传出的 HTTP 响应。有两种方式可以做到这一点。首先，你可以在资源上链式调用 response 方法。该方法会返回 Illuminate\Http\JsonResponse 实例，让你能够完全控制响应头：

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/user', function () {
    return User::find(1)
        ->toResource()
        ->response()
        ->header('X-Value', 'True');
});

你也可以直接在资源上定义 withResponse 方法。当资源作为响应中的最外层资源返回时，就会调用该方法：

<?php

namespace App\Http\Resources;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * 将资源转换为数组。
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
        ];
    }

    /**
     * 自定义传出的资源响应。
     */
    public function withResponse(Request $request, JsonResponse $response): void
    {
        $response->header('X-Value', 'True');
    }
}

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/laravel/13.x/el...

译文地址：https://learnku.com/docs/laravel/13.x/el...

Markdown 文本

从零开发一个电商项目，功能包括电商后台、商品 & SKU 管理、购物车、订单管理、支付宝支付、微信支付、订单退款流程、优惠券等

你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程，JWT 概念及使用和 API 开发相关的进阶知识。

贡献者：1

API 资源 13.x 13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Eloquent: API 资源

介绍

生成资源

资源集合

概念概述

资源集合

自定义资源集合

保留集合键

自定义底层资源类

编写资源

关联

资源集合

数据包裹

包裹嵌套资源

数据包裹与分页

分页

自定义分页信息

条件属性

合并条件属性

条件关联

条件关联数量

条件中间表信息

添加元数据

顶层元数据

构建资源时添加元数据

JSON:API 资源

生成 JSON:API 资源

定义属性

定义关联

$relationships 属性

包含关联

关联深度

资源类型与 ID

稀疏字段集与关联包含

忽略查询字符串

包含之前已加载的关联

链接与元数据

资源响应

推荐文章：

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

请登录

API 资源

13.x

13.x 12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

`$relationships` 属性