Laravel API 资源是为 Eloquent 模型封装可控 JSON 输出规范的类，通过 toArray() 实现字段过滤、关系嵌套、格式转换与安全脱敏；使用 make:resource 生成单资源或集合资源，配合 whenLoaded 避免 N+1，可继承自定义基类统一响应结构。
在 Laravel 中部署 API 资源（API Resources），本质是为 Eloquent 模型建立一层可控、可复用的 JSON 输出规范。它不是简单地调用 toJson()，而是通过类封装实现字段过滤、关系嵌套、格式转换和安全控制，让接口响应结构清晰、前后端职责分明。
生成资源类并定义基础结构
使用 Artisan 命令快速创建资源类，它会自动放在 app/Http/Resources 目录下，并继承 JsonResource：
-
php artisan make:resource UserResource→ 处理单个模型 -
php artisan make:resource User --collection或php artisan make:resource UserCollection→ 处理集合（如分页列表）
打开生成的 UserResource.php，重点修改 toArray() 方法。这里直接通过 $this 访问模型属性，例如：
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
'created_at' => $this->created_at->toISOString(),
];
控制输出字段与敏感信息
资源类天然支持字段精简和脱敏，避免意外暴露密码、remember_token 等字段：
- 不写进
toArray()的字段就不会出现在 JSON 中 - 可重命名字段（如用
user_id替代id） - 可添加计算属性（如
'full_name' => "{$this->first_name} {$this->last_name}"） - 可结合模型访问器（
getAvatarUrlAttribute）统一处理头像路径等逻辑
嵌套关联数据与按需加载
当需要包含关联模型（如用户的文章列表、所属角色）时，推荐在资源中嵌套其他资源类，并配合 Laravel 提供的条件方法避免 N+1 查询：
- 用
$this->whenLoaded('posts', fn() => PostResource::collection($this->posts))实现“仅当已预加载时才输出” - 用
$this->when($this->is_admin, ['is_super_admin' => true])控制字段是否出现 - 对集合资源（如
UserCollection），框架会自动识别LengthAwarePaginator并注入links和meta分页信息
统一响应格式与扩展能力
默认资源会把数据包在 data 键下，如需全局统一结构（如含 code、message、timestamp），可自定义基类：
- 新建
app/Http/Resources/ApiResource.php，继承JsonResource - 设置
public static $wrap = null关闭默认外层包装 - 重写
toArray()，合并业务数据与公共字段：array_merge(parent::toArray($request), ['code' => 200, 'message' => 'OK']) - 让所有业务资源（如
UserResource）继承该基类
