Laravel API 资源类用于统一 JSON 响应格式，1. 通过 make:resource 命令生成资源类；2. 在 toArray 方法中定义返回字段与结构；3. 控制器中返回单个资源或集合，自动适配分页；4. 使用 whenLoaded 等方法条件性包含数据避免 N+1 查询；5. 重写 with 方法添加全局状态信息，提升 API 规范性与可维护性。
Laravel 的 API 资源类（API Resource）用于将模型和模型集合转换为一致的 JSON 响应格式，特别适用于构建 RESTful API。它让你能清晰地控制返回给前端的数据结构，同时支持单个资源和资源集合的处理。
创建 API 资源类
使用 Artisan 命令可以快速生成资源类：
php artisan make:resource UserResource php artisan make:resource UserCollection // 或者直接用 UserResource::collection()
执行后会在 app/Http/Resources 目录下生成 UserResource.php 文件。
定义资源类结构
打开生成的资源类，toArray 方法决定了输出的 JSON 结构：
class UserResource extends JsonResource
{
public function toArray($request)
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
'created_at' => $this->created_at->toISOString(),
// 可以添加关联数据或计算字段
'profile' => new ProfileResource($this->whenLoaded('profile')),
];
}
}
$this 指向当前模型实例，你可以按需选择字段、格式化日期、嵌套其他资源等。
在控制器中使用资源类
在控制器中返回资源类，Laravel 会自动将其解析为 JSON：
use App\Http\Resources\UserResource;
use App\Models\User;
// 返回单个用户
public function show($id)
{
return new UserResource(User::findOrFail($id));
}
// 返回用户列表
public function index()
{
return UserResource::collection(User::all());
// 或分页时自动适配
// return UserResource::collection(User::paginate());
}
当你返回 UserResource::collection()，Laravel 会自动处理分页数据，包含元信息如 links 和 meta。
条件性包含数据
使用 when()、whenLoaded()、mergeWhen() 等方法可避免 N+1 查询并按条件返回字段：
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->when(auth()->user()->isAdmin(), $this->email),
'profile' => new ProfileResource($this->whenLoaded('profile')),
'posts_count' => $this->when(isset($this->posts_count), $this->posts_count),
];
比如 whenLoaded 只有在预加载了 profile 关联时才包含该字段，避免意外触发数据库查询。
自定义资源响应
如果需要添加额外顶层字段（如状态信息），可重写 with 方法：
public function with($request)
{
return [
'status' => 'success',
'timestamp' => now()->toISOString(),
];
}
这样每次返回该资源时都会附加这些信息。
基本上就这些。合理使用 Laravel API 资源类，可以让 API 数据结构更规范、更易维护，尤其适合前后端分离项目。
