使用 Laravel API 资源类可统一 JSON 返回格式，通过 make:resource 创建资源类，在 toArray 中定义字段，控制器中返回 new UserResource($user) 或 UserResource::collection() 实现数据结构化输出。
如果您在使用 Laravel 构建 API 时，希望对返回的 JSON 数据进行统一格式化和结构控制，可以利用 Laravel 提供的 API 资源类来实现更清晰、可维护的数据输出。通过资源类，您可以精确地定义每条数据字段的展示方式。
本文运行环境：MacBook Pro，macOS Sonoma
一、创建 API 资源类
API 资源类的作用是将 Eloquent 模型实例转换为 JSON 格式的数据，并允许您自定义字段映射逻辑。Laravel 的资源类提供了 clean 的方式来组织响应结构。
1、在终端中运行 Artisan 命令生成一个新的资源类：php artisan make:resource UserResource。
2、执行后将在 app/Http/Resources 目录下生成 UserResource.php 文件，该文件默认继承自 Illuminate\Http\Resources\Json\JsonResource。
二、定义单个资源的返回字段
在单个资源类中，您可以通过重写 toArray 方法来指定需要输出的字段。此方法接收当前模型实例作为上下文，允许您灵活处理属性。
1、打开 app/Http/Resources/UserResource.php 文件，在 toArray 方法中编写字段映射逻辑。
2、例如返回用户的基本信息：return ['id' => $this->id, 'name' => $this->name, 'email' => $this->email];。
3、当控制器返回 new UserResource($user) 时，系统会自动调用此方法并输出定义的 JSON 结构。
三、创建资源集合类
当需要返回多个模型记录时，应使用资源集合类以确保一致性和性能优化。集合类能批量处理资源实例并包装成数组形式。
1、可通过命令 php artisan make:resource UserCollection 创建独立集合类，或直接使用内置的 collection() 方法。
2、若选择手动创建，确保类继承自 Illuminate\Http\Resources\Json\ResourceCollection。
3、在 toArray 方法中可自定义分页元信息与数据列表，如：return ['data' => $this->collection, 'links' => ['self' => 'api/users']];。
四、在控制器中使用资源类
控制器负责调用资源类并将其实例作为响应返回。通过这种方式，业务逻辑与数据展示层得以分离，提升代码可读性。
1、在控制器方法中引入已定义的资源类，例如 use App\Http\Resources\UserResource;。
2、查询模型数据后将其封装进资源对象：return new UserResource(User::find($id));。
3、对于集合数据，使用 return UserResource::collection(User::all()); 可快速完成转换。
五、嵌套资源关系的处理
当模型之间存在关联关系（如一对多或多对多）时，可在资源类中嵌套其他资源以构建层次化 JSON 输出。
1、在父资源的 toArray 方法中添加关联字段，例如用户的文章列表：'posts' => PostResource::collection($this->whenLoaded('posts'))。
2、使用 $this->whenLoaded() 方法可避免 N+1 查询问题，仅在关系已预加载时才输出数据。
3、确保在查询时使用 with() 预加载相关模型，例如 User::with('posts')->get()，以提高性能。
