Laravel API Resource: 如何统一集合与单个资源的输出格式-php教程-PHP中文网

Laravel API Resource: 如何统一集合与单个资源的输出格式

花韻仙語

发布： 2025-11-28 10:38:22

原创

329人浏览过

Laravel API Resource: 如何统一集合与单个资源的输出格式

本文将详细介绍在laravel框架中，如何利用api资源（api resources）来统一格式化单个数据记录和数据集合的api响应。通过使用`resource::collection()`方法，开发者可以确保`index()`等返回多条记录的接口，也能获得与`show()`方法返回的单条记录一致的、经过资源类处理的json格式数据，从而提升api的规范性和可维护性。

理解Laravel API Resources

Laravel API Resources 提供了一种将 Eloquent 模型转换为 JSON 格式的强大而灵活的方式。它们允许您精确控制发送给应用程序客户端的数据，包括字段的筛选、数据的转换以及关联关系的加载。这对于构建清晰、一致且易于维护的 RESTful API 至关重要。

通常，我们会在控制器中使用资源来处理 API 响应。例如，当您需要返回单个模型实例时，可以直接实例化一个资源类：

// app/Http/Controllers/TestController.php

use App\Models\Test;
use App\Http\Resources\TestRessource; // 注意：原文拼写为Ressource，这里保持一致

class TestController 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 资源类：

// app/Http/Resources/TestRessource.php

use Illuminate\Http\Request;
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
        ];
    }
}

登录后复制

当访问 /Test/1 时，您会得到一个格式化的 JSON 响应，例如：

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

登录后复制

解决集合数据格式化不一致的问题

然而，当您尝试在 index() 方法中返回一个模型集合时，如果直接返回 Eloquent 集合，它将不会自动应用您的资源类定义的格式。例如，如果 index() 方法如下：

// app/Http/Controllers/TestController.php (错误的示例)

// ...
class TestController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function index()
    {
        return Test::all(); // 这样返回不会应用资源格式
    }
    // ...
}

登录后复制

访问 /Test 时，您会得到一个包含所有数据但未经过 TestRessource 格式化的原始 JSON 数组，这与 show() 方法的输出格式不一致，降低了 API 的规范性。

使用 Resource::collection() 统一集合数据格式

为了解决这个问题，Laravel 提供了一个专门用于处理资源集合的方法：Resource::collection()。这个静态方法会遍历给定的模型集合，并为集合中的每一个模型实例应用您的资源类定义的 toArray() 转换逻辑。

要正确格式化 index() 方法返回的集合数据，您需要修改 index() 方法如下：

vizcom.ai

AI草图渲染工具，快速将手绘草图渲染成精美的图像

139

查看详情

// app/Http/Controllers/TestController.php (正确的示例)

use App\Models\Test;
use App\Http\Resources\TestRessource; // 引入资源类

class TestController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return \Illuminate\Http\Resources\Json\AnonymousResourceCollection
     */
    public function index()
    {
        // 使用 TestRessource::collection() 来格式化所有 Test 模型
        return TestRessource::collection(Test::all());
    }

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

登录后复制

现在，当您访问 /Test 时，返回的 JSON 响应将是一个经过 TestRessource 格式化后的数据项数组，并且每个数据项都将包含在 data 键下（如果您的资源类是 JsonResource 的子类，并且没有自定义 with 方法）。例如：

{
    "data": [
        {
            "id": 1,
            "ref": "0103573026466442101007175850",
            "tax": null,
            "date_in": "2021-10-08T12:37:05.000000Z",
            "date_out": "2021-10-11T08:02:17.000000Z"
        },
        {
            "id": 2,
            "ref": "0103573026466442101007175851",
            "tax": "VAT",
            "date_in": "2021-10-09T10:00:00.000000Z",
            "date_out": "2021-10-12T09:00:00.000000Z"
        }
        // ... 更多数据项
    ]
}

登录后复制

注意事项与最佳实践

一致性是关键： 始终使用 Resource::collection() 来处理集合数据，以确保您的 API 响应在返回单个资源和资源集合时保持一致的结构和数据格式。
分页集成： Resource::collection() 同样适用于分页结果。如果您使用 Eloquent 的 paginate() 方法，可以直接将其结果传递给 collection()：
```
public function index()
{
    return TestRessource::collection(Test::paginate(15));
}
```
登录后复制
这将自动包含分页元数据（如 current_page, last_page, total 等）在响应中。

资源集合类： 对于更复杂的集合转换逻辑，您可以创建专门的资源集合类（例如 TestRessourceCollection），它继承自 Illuminate\Http\Resources\Json\ResourceCollection。这允许您在集合级别添加额外的元数据或转换逻辑。

// php artisan make:resource TestRessourceCollection --collection
// app/Http/Resources/TestRessourceCollection.php

use Illuminate\Http\Resources\Json\ResourceCollection;

class TestRessourceCollection extends ResourceCollection
{
    /**
     * The resource that this resource collects.
     *
     * @var string
     */
    public $collects = TestRessource::class; // 指定集合中的每个元素使用哪个资源类

    /**
     * Transform the resource collection into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array|\Illuminate\Contracts\Support\Arrayable|\JsonSerializable
     */
    public function toArray($request)
    {
        return [
            'data' => $this->collection, // 集合中的每个元素已由 TestRessource 转换
            'meta' => [
                'author' => 'Your Name',
                'timestamp' => now()->toDateTimeString(),
            ],
        ];
    }
}

登录后复制

然后在控制器中使用：

public function index()
{
    return new TestRessourceCollection(Test::all());
}

登录后复制

总结

通过正确使用 Laravel API Resources 的 Resource::collection() 方法，您可以轻松地统一 API 接口中单个资源和资源集合的输出格式。这不仅提高了 API 的可读性和一致性，也大大简化了前端开发人员与 API 的交互。对于需要自定义集合级别元数据或更复杂逻辑的场景，创建专门的资源集合类则提供了更高级的解决方案。掌握这些技巧，将使您的 Laravel API 更加健壮和专业。

以上就是Laravel API Resource: 如何统一集合与单个资源的输出格式的详细内容，更多请关注php中文网其它相关文章！

大家都在看：

PHP中高效判断MySQL表是否存在的方法与实践 php中unset函数的使用 php数组中array_count_values的使用 php如何实现数据去重插入_php唯一索引与先查后插优缺点对比 php中array_reduce累积处理数组_php归约函数实现累加拼接与自定义逻辑