Laravel如何实现API资源集合？（Resource Collection教程）

Laravel API资源集合用于统一格式化模型集合并返回JSON响应，需通过UserCollection封装分页或普通查询结果，自动处理字段、关系与分页结构。

在 Laravel 中，API 资源集合（Resource Collection）是用来统一格式化一组模型数据（比如 Eloquent 集合）并返回 JSON 响应的核心机制。它不是简单地循环输出数组，而是让批量数据的结构、字段、关系、分页等都保持与单个资源（Resource）一致的可控性和可维护性。

定义资源集合类

当你已有单个资源类（如 UserResource），可通过 Artisan 命令快速生成对应的集合类：

php artisan make:resource UserCollection

生成的 UserCollection.php 默认继承 ResourceCollection，并重写了 toArray() 方法。注意：它不自动调用每个模型的 UserResource，你需要显式委托：

• 推荐写法：直接返回 $this->collection，Laravel 会自动为每个模型实例调用对应资源类（前提是集合中每个项都是模型且资源类命名规范）
• 手动控制：也可用 $this->collection->mapInto(UserResource::class) 或 $this->collection->map(fn ($user) => new UserResource($user))

配合 API 路由和控制器使用

在控制器方法中，不要直接 return $users->toArray() 或 response()->json()，而是用资源封装：

• 返回普通集合：return new UserCollection(User::all());
• 返回分页结果（最常见）：return new UserCollection(User::paginate(10)); —— Laravel 自动识别分页器，并把 data、links、meta 等结构注入响应
• 需要额外字段？重写集合的 toArray()，例如添加总数量：

  public function toArray($request) { return [ 'data' => $this->collection, 'total' => $this->total(), ]; }

  登录后复制

处理嵌套关系和条件字段

资源集合本身不直接处理关系，逻辑仍放在单个资源类里。比如 UserResource 中写了 'posts' => PostCollection::make($this->whenLoaded('posts'))，那么在集合中每条用户数据都会按需加载并格式化 posts 关系。

若想在集合层统一加字段（如统计信息），可在集合的 toArray() 中添加：

• 'summary' => ['active_users' => $this->collection->where('status', 'active')->count()]
• 避免在集合里做 N+1 查询，关系预加载应在查询时完成：User::with('posts')->paginate(10)

自定义分页响应结构（可选进阶）

默认分页响应包含 data、first_page_url、last_page 等。如需精简或改名，可创建继承 ResourceCollection 的子类，并重写 paginationInformation() 方法：

• 返回空数组可去除所有分页字段（仅保留 data）
• 返回自定义键值对，比如 'pagination' => [...] 把分页信息包进一个顶层字段

基本上就这些。资源集合本质是“批量版资源”，核心就两点：用对类、交由框架自动处理映射，别绕过它手动遍历。

以上就是Laravel如何实现API资源集合？（Resource Collection教程）的详细内容，更多请关注php中文网其它相关文章！