Laravel API资源集合是强制封装层，必须配合命名匹配的单个资源类使用，分页响应需传入Paginator实例，不可手动构造数组，且资源类中避免耗时操作。
API 资源集合不是“可选优化”，而是 Laravel API 响应的强制封装层——绕过它直接 return $users->toArray() 或 response()->json()，等于放弃字段控制、关系加载、分页结构和统一错误边界。
资源集合必须配合单个资源类使用
生成 UserCollection 后，它默认只做一件事：把 $this->collection 交给每个模型去调用对应的单个资源类（如 UserResource）。这个委托机制依赖命名规范和自动发现，不手动指定就失效。
- 确保单个资源类存在且命名匹配：
UserCollection会尝试调用UserResource，不是UserRes或userResource - 若命名不一致（比如用了
ApiUserResource），必须显式委托：return $this->collection->mapInto(ApiUserResource::class) - 不要在集合里重复写字段逻辑——所有字段映射、
whenLoaded、访问器处理都应在UserResource::toArray()中完成 - 如果单个资源类还没建，先运行
php artisan make:resource UserResource，再建集合
分页响应不能靠 toArray() 硬塞
Laravel 对 Paginator 实例有特殊识别逻辑：只有传入 User::paginate() 这类返回 LengthAwarePaginator 的结果时，UserCollection 才会自动注入 data、links、meta 等标准分页字段。手动构造数组再塞进去，等于白写。
- 正确写法：
return new UserCollection(User::with('posts')->paginate(15)) - 错误写法：
return new UserCollection(User::all()->forPage(1, 15))—— 这只是普通集合，没分页元信息 - 想改分页键名（比如把
data改成items），重写paginationInformation()方法，而不是在toArray()里覆盖整个结构 - 分页前务必预加载关联，否则
whenLoaded('posts')在每条数据里触发 N+1 查询
collect() 和 ResourceCollection 别混用
collect() 是处理内存中数组的工具；ResourceCollection 是格式化 Eloquent 集合/分页器为 JSON 响应的协议层。两者目的、生命周期、适用场景完全不同，强行套用会导致结构错乱或静默失败。
- 从请求拿到的
$request->input('items')是普通数组？用collect($request->input('items') ?? [])处理，别喂给UserCollection -
UserCollection只接受 Eloquent 集合（Collection）或分页器（Paginator），传collect([…])会报错或返回空data - 需要对 API 响应前的数据做清洗（比如过滤掉敏感字段）？在查询后、封装进资源前用集合方法：
User::all()->filter(…)->values()，再传给UserCollection - 调试时想看中间结果？在链式调用里加
->tap(fn($c) => dd($c))，别用dd()直接打断资源流程
最容易被忽略的是资源类的生命周期——它不缓存、不复用、每次请求都新建实例。如果你在 toArray() 里做了耗时操作（比如查库、远程调用），性能会随集合大小线性恶化。所有外部依赖必须前置到控制器或查询层完成。
