laravel 的 api resource 提供了一种将 eloquent 模型转换为 json 结构的方法，而 resource collection 则用于处理模型集合。当需要对数据进行分页时，laravel 的分页器会返回一个包含数据、分页链接和元数据的对象。要将这些信息完整地暴露给 api 消费者，最常见且推荐的做法是将分页器实例直接传递给一个 resourcecollection。
示例：创建用户资源和集合
首先，假设我们有一个 User 模型和对应的 UserResource：
// app/Http/Resources/UserResource.php
namespace App\Http\Resources;
use Illuminate\Http\Resources\Json\JsonResource;
class UserResource extends JsonResource
{
public function toArray($request)
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
// ... 其他用户属性
];
}
}
// app/Http/Resources/UserCollection.php
namespace App\Http\Resources;
use Illuminate\Http\Resources\Json\ResourceCollection;
class UserCollection extends ResourceCollection
{
public $collects = UserResource::class; // 指定集合中每个元素使用的资源
public function toArray($request)
{
// ResourceCollection 默认会自动处理分页链接和元数据
// 你可以在这里添加额外的元数据，例如：
return parent::toArray($request);
}
}在控制器或路由中返回分页数据
当您从控制器或路由返回一个 ResourceCollection 实例，并将一个分页器（例如 User::paginate()）传递给它时，Laravel 会自动将分页链接和元数据包含在 JSON 响应中。
// routes/web.php 或 routes/api.php
use App\Http\Resources\UserCollection;
use App\Models\User;
use Illuminate\Support\Facades\Route;
Route::get('/users', function () {
// User::paginate() 返回一个 Illuminate\Pagination\LengthAwarePaginator 实例
return new UserCollection(User::paginate());
});上述代码将生成一个包含 data 数组（实际用户数据）、links 对象（包含分页链接如 first, last, prev, next）和 meta 对象（包含分页元数据如 current_page, from, to, total 等）的 JSON 响应。
{
"data": [
{
"id": 1,
"name": "User 1",
"email": "user1@example.com"
},
{
"id": 2,
"name": "User 2",
"email": "user2@example.com"
}
],
"links": {
"first": "http://localhost/users?page=1",
"last": "http://localhost/users?page=5",
"prev": null,
"next": "http://localhost/users?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 5,
"path": "http://localhost/users",
"per_page": 15,
"to": 15,
"total": 75
}
}在某些情况下，您可能希望在一个资源的内部包含一个已分页的关联集合。例如，一个 Section 资源可能包含多个 Item，并且您希望这些 Item 能够分页。
原始问题中的代码示例：
// app/Http/Resources/SectionResource.php
public function toArray($request)
{
return [
"name" => $this->name,
"slug" => $this->slug,
"bg_image" => imageGenerate("sections" , $this->bg_image),
"bg_color" => $this->bg_color,
// 这里尝试对 items 进行分页并用 ItemCollection 包装
"items" => new ItemCollection($this->items()->paginate(20)),
];
}
// app/Http/Resources/ItemCollection.php
public function toArray($request)
{
// 这里的 $this->collection 已经是分页器返回的当前页数据
return $this->collection->map(function ($item) {
return [
"id" => $item->id,
"name" => $item->name,
"slug" => $item->slug,
"image" => imageGenerate("items" , $item->image),
"code" => $item->code,
"category" => $item->category->name??""
];
});
}解释与注意事项：
尽管在 SectionResource 内部对 items 进行了 paginate() 操作并用 ItemCollection 进行了包装，但当 ItemCollection 被嵌套在另一个 JsonResource (即 SectionResource) 的 toArray 方法中时，ItemCollection 的 links 和 meta 分页信息将不会被自动提升到 SectionResource 的根级别响应中。
这是因为 JsonResource (如 SectionResource) 的 toArray 方法期望返回一个简单的数组结构。当 new ItemCollection(...) 被调用时，ItemCollection 的 toArray 方法会被执行，它通常返回的是其内部的 data 数组（即当前页的 Item 列表），而不是包含 links 和 meta 的完整分页响应。
换句话说，SectionResource 的响应会是这样的：
{
"name": "Section Name",
"slug": "section-slug",
"bg_image": "...",
"bg_color": "#FFF",
"items": [ // 这是一个普通的数组，只包含当前页的 Item 数据
{
"id": 101,
"name": "Item 1",
// ...
},
{
"id": 102,
"name": "Item 2",
// ...
}
// ... (最多20个 Item)
]
}您会发现 items 数组中没有分页链接或元数据。要获取这些分页信息，ItemCollection 必须作为 API 响应的顶级资源返回。
为了提供清晰且易于消费的 API，以下是一些处理分页的建议：
单一责任原则： Laravel ResourceCollection 的设计初衷是作为顶级响应来处理分页。如果您需要对某个集合进行分页并暴露其分页信息，那么这个集合应该成为该 API 路径的主要返回内容。
为嵌套集合创建独立 API 端点： 如果 Section 资源下的 items 需要独立分页并展示分页链接，最佳实践是为 items 创建一个独立的 API 端点。例如：
示例：独立的项目分页 API
// routes/api.php
use App\Http\Resources\ItemCollection;
use App\Models\Section;
Route::get('/sections/{section}/items', function (Section $section) {
return new ItemCollection($section->items()->paginate(20));
});这样，访问 /api/sections/{section_id}/items 将会返回一个包含 data、links 和 meta 的完整分页响应，专门针对该分区下的项目。
手动添加分页元数据（不推荐常规使用）： 如果您确实需要在父资源中包含嵌套集合的分页元数据，您需要手动从分页器中提取这些信息并将其添加到父资源的响应中。但这会使您的资源变得复杂，并可能偏离标准的 API 响应模式。
// app/Http/Resources/SectionResource.php (仅作示例，不推荐常规使用)
public function toArray($request)
{
$itemsPaginator = $this->items()->paginate(20);
return [
"name" => $this->name,
"slug" => $this->slug,
"bg_image" => imageGenerate("sections" , $this->bg_image),
"bg_color" => $this->bg_color,
"items" => new ItemCollection($itemsPaginator), // 传递分页器，但 ItemCollection 内部只返回 data
"items_pagination_meta" => [ // 手动添加元数据
'current_page' => $itemsPaginator->currentPage(),
'last_page' => $itemsPaginator->lastPage(),
'per_page' => $itemsPaginator->perPage(),
'total' => $itemsPaginator->total(),
// ... 其他你需要的元数据
],
"items_pagination_links" => [ // 手动添加链接
'first' => $itemsPaginator->url(1),
'last' => $itemsPaginator->url($itemsPaginator->lastPage()),
'prev' => $itemsPaginator->previousPageUrl(),
'next' => $itemsPaginator->nextPageUrl(),
],
];
}这种方式虽然能实现目的，但会增加客户端解析的复杂性，且不符合 Laravel ResourceCollection 的设计意图。
Laravel API Resource 和 Collection 提供了强大且灵活的方式来构建 API 响应。当涉及到分页时，最简洁和符合规范的做法是让 ResourceCollection 作为顶级响应来处理分页数据，这样它能够自动包含 data、links 和 meta 等完整的分页信息。对于嵌套的关联数据，如果需要分页，建议为其创建独立的 API 端点，以保持 API 结构清晰和易于维护。遵循这些最佳实践将有助于您构建高效、可扩展且易于消费的 Laravel API。
以上就是在 Laravel API Resource 中正确处理分页链接的详细内容，更多请关注php中文网其它相关文章！
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移，垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是，许多工具可以让 Windows 保持平稳运行。
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号
175
收藏
