如何合理构建Laravel API Resources文件夹结构？社区最佳实践探讨

1. 按模型类型组织全局资源目录 #

别再按路由/模块拆分资源了，社区主流做法是按模型归类。比如把所有用户相关的资源都放在App\Http\Resources\User目录下，根据数据粒度定义不同的资源类，比如BasicUserResource、DetailedUserResource。这样不管是users/user还是holiday/user路由，只要需要相同的用户数据结构，直接复用同一个资源类就行，完全不用重复创建。

示例代码：

// App\Http\Resources\User\BasicUserResource.php
namespace App\Http\Resources\User;

use Illuminate\Http\Resources\Json\JsonResource;

class BasicUserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'firstname' => $this->firstname,
            'fullName' => $this->fullName(),
        ];
    }
}

在不同路由的控制器里直接引用：

// UsersController
return new \App\Http\Resources\User\BasicUserResource($user);

// HolidayController
return new \App\Http\Resources\User\BasicUserResource($user);

2. 用条件加载控制冗余数据 #

担心全局资源会返回多余字段？可以利用Laravel资源的上下文判断或动态字段加载功能：

• 基于路由判断：

public function toArray($request)
{
    $baseData = [
        'id' => $this->id,
        'name' => $this->name,
        'firstname' => $this->firstname,
        'fullName' => $this->fullName(),
    ];

    // 仅在用户模块路由下返回邮箱
    if ($request->routeIs('users.*')) {
        $baseData['email'] = $this->email;
    }

    return $baseData;
}

• 用Laravel自带的when方法简化：

return [
    'id' => $this->id,
    'name' => $this->name,
    'firstname' => $this->firstname,
    'fullName' => $this->fullName(),
    'email' => $this->when($request->routeIs('users.*'), $this->email),
];

• 甚至可以通过请求参数动态控制：

'email' => $this->when($request->has('include_email'), $this->email),

3. 资源继承减少重复代码 #

如果同一模型的不同资源大部分字段相同，只有少量差异，直接用继承复用基础字段：

// 基础用户资源（通用字段）
class BasicUserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'firstname' => $this->firstname,
            'fullName' => $this->fullName(),
        ];
    }
}

// 详细用户资源（扩展字段）
class DetailedUserResource extends BasicUserResource
{
    public function toArray($request)
    {
        return array_merge(parent::toArray($request), [
            'email' => $this->email,
            'created_at' => $this->created_at->toIso8601String(),
            'updated_at' => $this->updated_at->toIso8601String(),
        ]);
    }
}

4. 避开按路由划分资源的坑 #

按路由/模块创建资源看似符合路由结构，但本质是把数据结构和业务路由绑定，会导致大量重复代码——毕竟不同模块经常需要同一模型的相同数据视图。Laravel社区的共识是：资源应该服务于模型的数据表示，而不是路由结构。

内容的提问来源于stack exchange，提问作者Enzo