必须通过 API 资源集合封装模型数据以实现统一 JSON 响应，方法包括：一、artisan make:resource 生成；二、手动创建继承 ResourceCollection；三、--collection 标志生成；四、控制器中实例化返回；五、重写 toArray 扩展结构。
如果您在构建 Laravel API 时需要将一组模型数据（如分页结果或查询集合）以统一、可控的 JSON 结构返回，则必须通过 API 资源集合（Resource Collection）进行封装。以下是定义 API 资源集合的具体方法：
一、使用 Artisan 命令生成资源集合类
这是最标准、推荐的初始化方式，可自动生成继承 ResourceCollection 的类文件，并预置基础结构。
1、在终端中执行命令：php artisan make:resource UserCollection。
2、该命令将在 app/Http/Resources/ 目录下创建 UserCollection.php 文件。
3、生成的类默认继承 Illuminate\Http\Resources\Json\ResourceCollection，且 toArray() 方法已声明为返回 $this->collection。
二、手动创建资源集合类并继承 ResourceCollection
当需完全控制命名空间、文件位置或复用已有逻辑时，可跳过 Artisan 命令，直接手写类文件，确保其正确继承并实现核心行为。
1、在 app/Http/Resources/ 下新建 PostCollection.php 文件。
2、定义类并继承 ResourceCollection：class PostCollection extends ResourceCollection。
3、在 toArray() 方法中显式返回 ['data' => $this->collection] 或添加其他元字段。
三、通过 --collection 标志生成集合类
此方式与第一种等效，但更明确地声明意图，适用于已有单个资源类需配套生成集合类的场景。
1、若已存在 UserResource，运行：php artisan make:resource UserCollection --collection。
2、Laravel 将识别 --collection 参数，生成专用于集合的类，而非单个资源类。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
3、生成类中 toArray() 方法默认委托给 $this->collection，无需额外修改即可支持自动调用对应单个资源类。
四、在控制器中实例化资源集合返回响应
资源集合类本身不处理 HTTP 响应，需在控制器中主动实例化，由 Laravel 自动转换为 JSON 并设置 Content-Type。
1、在控制器方法中获取 Eloquent 集合，例如：$users = User::paginate(15);。
2、使用 new UserCollection($users) 包裹该结果。
3、直接 return 该实例：return new UserCollection(User::paginate(10));。
4、Laravel 将自动识别分页器，注入 data、links、meta 等标准字段。
五、重写 toArray 方法以扩展响应结构
当需在集合层级添加总数、摘要、链接或其他元信息时，必须覆盖默认的 toArray() 方法，以控制顶层 JSON 键值结构。
1、在 UserCollection.php 中修改 toArray() 方法签名。
2、返回关联数组，其中 data 键存放格式化后的集合项：'data' => $this->collection。
3、在同一层级添加其他字段，例如：'total' => $this->total(), 'per_page' => $this->perPage()。
4、若需嵌套统计信息，可使用集合方法计算：'summary' => ['active_count' => $this->collection->where('status', 'active')->count()]。
