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' => [...]把分页信息包进一个顶层字段
基本上就这些。资源集合本质是“批量版资源”，核心就两点：用对类、交由框架自动处理映射，别绕过它手动遍历。
