必须用 Resource 类做 API 数据格式转换，它是数据流强制闸门；字段需显式声明，关联须预加载+whenLoaded，分页需链式 response() 或自定义集合类，OpenAPI 文档须手动注解。
必须用
类做 API 数据格式转换，直接
或手动构造数组会失控——字段漏写、N+1、敏感信息暴露、分页结构丢失，全在控制器里硬拼时埋下。
Resource 类的
是唯一可信出口
它不是“美化层”，而是数据流强制闸门。返回什么，JSON 就长什么样；没写的字段，前端永远收不到；写错逻辑，就直接暴露密码或 null 引用。
会触发模型访问器，但前提是这一行被显式写进
返回数组里
日期别依赖模型
或全局设置：
才可靠，
防 null
关联字段不能直接写
——未预加载时会懒加载，一次请求变几十次查询
要嵌套关联，必须配合
不等于循环 new
它跳过单个资源构造函数，批量处理，性能更好，也避免了你在
里加日志、缓存等副作用被意外执行。
传
返回空数组
；传
给
直接报错
如果用了分页（如
），
只返回
数组，
和
全丢——必须链式调用
想加
包裹或自定义分页字段，得单独建集合类：
，并在
里手动组织结构
条件字段和敏感字段靠显式控制，不靠“默认过滤”
Resource 没有自动白名单或隐藏规则。漏写 = 安全，写错 = 泄露。所有判断都得你亲手写进
。
Laravel 13.2.0
PHP中文网提供Laravel 13.2.0版本下载，Laravel框架 是基于 PHP 8.3+ 的高性能框架，官方推荐通过 Composer 安装。它内置 AI SDK、JSON:API Resources 及原生向量搜索，支持属性驱动开发与队列路由，大幅提升开发效率。相比旧版，13.2.0 优化了缓存 TTL 管理与实时通信，无需 Redis 即可横向扩展。作为现代 Web 开发首选，它兼顾安全与极速体验，助您快速构建企业级应用。
下载
用
替代 if 分支，兼容 collection 场景
批量加调试字段：
永远不要在
里调用
或复杂模型方法——资源应无状态，查询必须由控制器预加载完成
字段映射别硬编码：数据库存
，前端要
，就在
里写
OpenAPI 文档不会自动读取 Resource 类
无论你把
写得多规范，
或
都不会去解析它。它们只认控制器方法上的注解。
返回集合时，必须写
，不能只写
用了
动态字段？得用
显式标注可选性
嵌套了
？文档里不会自动展开
，得手写
自定义响应包装（如
）？必须用
贴 JSON 示例，否则文档为空
真正容易被忽略的点是：资源类里没有“魔法”，只有你写的每一行 PHP 逻辑；而最危险的疏忽，往往发生在你认为“这个字段肯定有值”“那个关联肯定已加载”的时候。
ResourcetoArray()toArray()$this->nametoArray()$casts$this->created_at?->toISOString()?->'posts' => $this->posts$this->whenLoaded('posts', fn() => PostResource::collection($this->posts))UserResource::collection()__construct()collect([])[]nullnew UserResource($user)User::paginate(10)UserResource::collection($users)datalinksmeta->response()dataphp artisan make:resource UserCollection --collectiontoArray()toArray()$this->when($this->can('admin'), 'is_admin')mergeWhen($request->user()->isSuperAdmin(), ['sql_log' => []])toArray()$this->load()activeis_activetoArray()'is_active' => (bool) $this->activetoArray()scribelaravel-openapi@responseCollection App\Http\Resources\UserResource@responsewhen()@responseField nullable$this->whenLoaded('profile')profile.id@responseField profile.idreturn response()->json(['items' => $resource])@response