Laravel API 资源集合的统一格式化处理

日期：2025-12-03 00:00 / 作者：碧海醫心

本文详细阐述了在 Laravel 中如何利用 API 资源（API Resources）确保数据集合（如列表查询）与单个数据项（如详情查询）返回统一的 JSON 格式。通过引入 `Resource::collection()` 方法，开发者可以高效地将模型集合转换为标准化的 JSON 响应，避免了手动迭代和格式化，从而实现 API 接口输出的一致性与规范性，提升开发效率和接口可维护性。

1. 理解 Laravel API 资源的作用

Laravel API 资源提供了一种将 Eloquent 模型转换为 JSON 格式的便捷方式，它允许开发者精确控制 API 响应中包含哪些属性以及它们的格式。这对于构建清晰、一致的 RESTful API 至关重要。

通常，我们会在控制器（Controller）的 show 方法中返回单个资源的详细信息，例如：

// app/Http/Controllers/MyController.php

namespace App\Http\Controllers;

use App\Models\Test;
use App\Http\Resources\TestRessource;

class MyController extends Controller
{
    /**
     * Display the specified resource.
     *
     * @param  \App\Models\Test  $test
     * @return \App\Http\Resources\TestRessource
     */
    public function show(Test $test)
    {
        return new TestRessource($test);
    }

    // ... 其他方法
}

对应的 TestRessource 定义了资源的具体结构，通过 toArray 方法指定了哪些模型属性应该被包含在 JSON 响应中：

// app/Http/Resources/TestRessource.php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class TestRessource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array|\Illuminate\Contracts\Support\Arrayable|\JsonSerializable
     */
    public function toArray($request)
    {
        return [
            "id" => $this->id,
            "ref" => $this->ref,
            "tax" => $this->tax,
            "date_in" => $this->date_in,
            "date_out" => $this->date_out
        ];
    }
}

当访问如 http://127.0.0.1/Test/1 这样的单个资源接口时，会得到如下格式化的 JSON 响应，其中数据被包裹在 data 键下：

{
    "data": {
        "id": 1,
        "ref": "0103573026466442101007175850",
        "tax": null,
        "date_in": "2025-10-08T12:37:05.000000Z",
        "date_out": "2025-10-11T08:02:17.000000Z"
    }
}

2. 集合数据格式化挑战与期望

在处理数据集合时，例如在 index 方法中返回所有 Test 模型的列表，开发者可能会遇到一个问题：如何让集合数据也遵循 TestRessource 定义的统一格式，即每个元素都经过格式化，并且整个集合也包裹在 data 键下？

如果直接在 index 方法中返回 Test::all()，或者错误地尝试 new TestRessource(Test::all())，将无法得到期望的、每个元素都经过 TestRessource 格式化的 JSON 数组。前者会输出模型原始的属性，后者则可能因为 JsonResource 期望单个模型实例而导致意外行为或错误。

我们期望的 index 接口（例如 http://127.0.0.1/Test）返回的 JSON 格式应是包含一个格式化对象数组的 data 键，类似于：

{
    "data": [
        {
            "id": 1,
            "ref": "0103573026466442101007175850",
            "tax": null,
            "date_in": "2025-10-08T12:37:05.000000Z",
            "date_out": "2025-10-11T08:02:17.000000Z"
        },
        {
            "id": 2,
            "ref": "...",
            "tax": null,
            "date_in": "...",
            "date_out": "..."
        }
        // ... 更多 Test 对象
    ]
}

3. 使用 Resource::collection() 格式化集合

Laravel 提供了一个专门用于处理资源集合的静态方法：collection()。这个方法允许你将一个 Eloquent 模型集合传递给你的资源类，它会自动遍历集合中的每个模型，并为每个模型应用资源类的 toArray 方法进行格式化。

要解决 index 方法的格式化问题，只需修改 index 方法如下：

// app/Http/Controllers/MyController.php

namespace App\Http\Controllers;

use App\Models\Test;
use App\Http\Resources\TestRessource;

class MyController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return \Illuminate\Http\Resources\Json\ResourceCollection
     */
    public function index()
    {
        // 正确的做法：使用资源类的 collection() 静态方法
        return TestRessource::collection(Test::all());

        // 如果需要分页，可以这样使用：
        // return TestRessource::collection(Test::paginate(15));
    }

    // ... 其他方法
}

在这里，TestRessource::collection(Test::all()) 会执行以下操作：

获取 Test::all() 返回的 Illuminate\Database\Eloquent\Collection 实例（或其他可迭代的集合）。
为集合中的每一个 Test 模型创建一个 TestRessource 实例。
调用每个 TestRessource 实例的 toArray 方法来格式化数据。
最终将所有格式化后的数据封装在一个顶层的 data 键下（这是 JsonResource 集合的默认行为），形成一个统一的 JSON 数组。

4. 注意事项与最佳实践

资源集合类型: JsonResource::collection() 方法返回的是一个 Illuminate\Http\Resources\Json\ResourceCollection 实例。如果你需要更精细地控制集合的顶层结构（例如添加自定义的元数据 meta 或链接 links），你可以创建一个专门的资源集合类，继承自 ResourceCollection。

// app/Http/Resources/TestCollection.php
namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class TestCollection extends ResourceCollection
{
    /**
     * 默认的 "data" 包装器。
     *
     * @var string|null
     */
    public static $wrap = 'data'; // 默认就是 'data'，可以修改或设置为 null 取消包装

    /**
     * 将资源集合转换为数组。
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array|\Illuminate\Contracts\Support\Arrayable|\JsonSerializable
     */
    public function toArray($request)
    {
        return [
            'data' => $this->collection, // $this->collection 包含了所有经过 TestRessource 格式化的数据
            'meta' => [
                'count' => $this->collection->count(),
                'total_pages' => $this->resource->lastPage() ?? 1, // 仅当使用分页时
                // ... 其他自定义元数据
            ],
            'links' => [
                'self' => url('/api/tests'),
                // ... 其他链接
            ],
        ];
    }
}

在这种情况下，控制器中的 index 方法应改为 return new TestCollection(Test::all());。然而，对于大多数简单场景，直接使用 TestRessource::collection() 已经足够，它会自动处理 data 包装。

分页支持: collection() 方法与 Laravel 的分页器完美结合。如果你正在使用 Test::paginate(15) 来获取分页数据，可以直接将其传递给 collection() 方法：
```
return TestRessource::collection(Test::paginate(15));
```
这将自动包含分页相关的 meta 和 links 信息，使得 API 响应更加完整和符合标准。
一致性: 始终使用 API 资源来格式化所有对外暴露的数据，无论是单个资源还是资源集合，以确保 API 响应的结构一致性。这种一致性对于前端开发、第三方集成以及长期维护都至关重要。

总结

通过在控制器 index 方法中采用 TestRessource::collection(Test::all()) 这种方式，我们能够高效且优雅地将数据库中的模型集合转换为统一、格式化的 JSON 响应。这不仅简化了代码，更重要的是保证了 API 接口在处理单个资源和资源集合时输出格式的一致性，从而提升了整个 API 的专业性和可维护性。理解并正确运用 collection() 方法是 Laravel API 开发中的一项基本且重要的技能。