Laravel API资源类可将Eloquent模型转为结构化JSON，通过UserResource的toArray方法自定义字段命名、格式化日期、添加计算属性，并嵌套PostResource处理关联数据，结合whenLoaded和when方法实现按需加载与条件输出，提升API安全性与可维护性。

Laravel 的 API 资源（API Resources）提供了一种优雅的方式来将 Eloquent 模型转化为结构清晰的 JSON 响应。通过使用资源类，你可以精确控制返回给前端的数据格式，包括字段命名、嵌套关系、条件属性等。

创建 API 资源类

要格式化 JSON 输出，先为模型创建对应的资源类。例如，假设你有一个 User 模型：

这会生成一个 UserResource 类，位于 app/Http/Resources 目录下。该类中包含一个 toArray 方法，用于定义输出字段：

public function toArray($request)
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'created_at' => $this->created_at->toISOString(),
    ];
}

格式化字段与自定义属性

在 toArray 方法中，你可以重命名字段、添加计算属性或格式化日期：

• 将 user_name 替代原始的 name 字段
• 添加全名、头像 URL 等衍生数据
• 使用 Carbon 格式化时间

return [
    'user_id' => $this->id,
    'user_name' => $this->name,
    'profile_image' => $this->avatar ? asset('storage/' . $this->avatar) : null,
    'full_name' => "{$this->first_name} {$this->last_name}",
    'registered_at' => $this->created_at->format('Y-m-d H:i:s'),
];

处理关联数据

当需要包含关联模型时，可以嵌套其他资源类。比如用户有多个文章：

use App\Http\Resources\PostResource;

return [
    'id' => $this->id,
    'name' => $this->name,
    'posts' => PostResource::collection($this->whenLoaded('posts')),
];

whenLoaded 方法确保只有在关系被预加载时才包含数据，避免 N+1 查询问题。

条件性字段输出

某些字段可能只对特定用户可见，可用 when 方法实现条件输出：

'reset_token' => $this->when($request->user()->isAdmin(), $this->reset_token),
'email_verified' => $this->when($this->email_verified_at, true),

这样可防止敏感信息泄露，同时保持响应结构整洁。

基本上就这些。合理使用 Laravel 资源类，能让 API 返回的 JSON 更规范、更安全，也更容易维护。