Laravel如何使用API Resource格式化输出_Laravel集合资源Transform字段处理【指南】

应继承 ResourceCollection 并重写 toArray() 方法统一处理集合元数据；单个 Resource 中通过显式返回键控制字段，用 when() 动态添加、排除敏感字段；日期、金额等需手动格式化以保证统一。

API Resource里怎么处理集合的字段映射

直接用 ResourceCollection 包裹集合时，Laravel 默认会把每个模型原样转成对应单个资源（比如 UserResource），但字段映射逻辑全在单个资源里。如果你需要对整个集合做统一字段增删、重命名或计算（比如加一个 total_count 字段），不能靠单个资源内部处理——它只管当前模型实例。

正确做法是继承 ResourceCollection 并重写 toArray()：

class UserCollection extends ResourceCollection
{
    public function toArray($request)
    {
        return [
            'data' => $this->collection,
            'meta' => [
                'total' => $this->total(),
                'per_page' => $this->perPage(),
                'current_page' => $this->currentPage(),
            ],
        ];
    }
}

注意：$this->collection 是已通过单个 UserResource 处理过的数据，不是原始模型集合。别试图在这里再调用 map() 去手动 transform 模型——那会绕过 Resource 的字段控制逻辑，导致隐藏字段泄露或格式错乱。

Transform字段时如何排除敏感字段或动态添加字段

在单个 Resource 类（如 UserResource）中，toArray() 返回的数组就是最终输出结构。字段是否出现，完全由你返回的键决定。Laravel 不会自动过滤 $hidden 或 $casts，除非你显式不返回它们。

• 要排除密码字段：别写 'password' => $this->password
• 要动态加字段：比如根据请求参数加权限标识，可用 $request->user()->can('view', $this->resource)
• 要条件性包含字段：用三元或空合并操作符，例如 'avatar_url' => $this->when($this->resource->avatar, fn() => $this->resource->avatar->url)

when() 和 mergeWhen() 是 Resource 内置的懒加载工具，避免 N+1 或无效字段计算。别用 isset() 或 !empty() 手动判断——Resource 实例的属性访问是延迟的，直接读可能触发不必要的查询。

为什么用 ResourceCollection 时分页信息丢失或格式不对

常见错误是直接 new 一个 ResourceCollection 并传入普通数组或 Collection，而不是 Eloquent 分页器（LengthAwarePaginator）。只有分页器对象才带 total()、currentPage() 这些方法。

确保控制器里这样调用：

return new UserCollection(User::paginate(15));

而不是：

return new UserCollection(User::all()); // ❌ 没有分页方法，total() 会报错

如果必须用普通集合但又要模拟分页字段，可以在 UserCollection::toArray() 里硬编码或从请求中取 per_page 参数，但这是权宜之计——真实分页逻辑必须由数据库层支持，否则 offset 越大性能越差。

API Resource 中日期格式和数字精度怎么统一控制

Resource 不会自动应用模型的 $casts 或 Carbon 序列化规则。比如模型里 $casts = ['created_at' => 'datetime:Y-m-d H:i:s']，在 Resource 里不写明，就还是默认 ISO8601 格式。

统一处理建议：

• 日期字段：用 $this->resource->created_at?->format('Y-m-d H:i:s')，注意空合并（?->）防 null
• 金额字段：用 number_format($this->resource->price, 2, '.', '')，避免浮点数精度问题
• 布尔值：显式转 (bool) 或 $this->resource->active ? true : false，防止数据库存的是 tinyint 导致前端收到 1/0

这些转换逻辑一旦散落在多个 Resource 里，后期难维护。更稳妥的方式是把通用格式封装进 trait 或基类 Resource，但要注意别过度抽象——很多项目只需要两三个 Resource，加一层继承反而增加理解成本。