本教程详细阐述如何在 laravel 控制器的 `index` 方法中，利用 api 资源（resource）正确地格式化并返回 eloquent 模型集合。通过对比单个资源与资源集合的处理方式，我们将学习如何使用 `resource::collection()` 方法，确保批量数据输出与单个数据保持一致的 json 结构，从而提升 api 的规范性和可维护性。
1. 理解 Laravel API 资源
Laravel API 资源（API Resources）提供了一种将 Eloquent 模型或模型集合转换为 JSON 格式的强大且灵活的方式。它们允许开发者自定义 API 响应的结构，隐藏不必要的数据库字段，并确保数据输出的一致性。通常，我们会在 app/Http/Resources 目录下创建资源类，例如 TestRessource。
以下是一个 TestRessource 的示例，它定义了单个 Test 模型在 API 响应中的 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
];
}
}2. 处理单个资源：show 方法
当我们需要返回单个 Eloquent 模型时，例如在 show 方法中根据 ID 获取特定记录，可以直接实例化资源类并传入模型实例。
// app/Http/Controllers/TestController.php
namespace App\Http\Controllers;
use App\Models\Test;
use App\Http\Resources\TestRessource; // 引入资源类
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);
}
// ... 其他方法
}访问 /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"
}
}Laravel 默认会将单个资源包装在一个 data 键下。
3. 处理资源集合：优化 index 方法
在 index 方法中，我们的目标是返回所有 Test 模型的集合，并且每个模型都应遵循 TestRessource 定义的格式。直接返回 Test::all() 将会得到未经格式化的原始模型数据，这不符合 API 的一致性要求。
为了正确地格式化模型集合，Laravel 提供了 Resource::collection() 静态方法。这个方法接收一个 Eloquent 模型集合（或任何 Illuminate\Support\Collection 实例），并为集合中的每个模型应用资源转换，最终返回一个包含所有格式化资源的集合响应。
将 TestController 的 index 方法更新如下：
// app/Http/Controllers/TestController.php
namespace App\Http\Controllers;
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()
{
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 路由时，您将获得一个包含所有 Test 记录的格式化 JSON 集合：
{
"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": "...",
"tax": "...",
"date_in": "...",
"date_out": "..."
}
// ... 更多 Test 记录
]
}与单个资源类似，集合资源也会被包装在 data 键下，但其值为一个 JSON 数组。
4. 注意事项与最佳实践
- 区分单例与集合： 始终记住，对于单个模型实例使用 new Resource($model)，对于模型集合使用 Resource::collection($collection)。这是使用 Laravel API 资源的核心区别。
-
分页支持： Resource::collection() 方法与 Laravel 的分页器（如 paginate() 或 simplePaginate()）无缝集成。当您将分页结果传递给 collection() 方法时，Laravel 会自动包含分页元数据。
public function index() { return TestRessource::collection(Test::paginate(15)); }这将返回一个包含分页元数据（如当前页、总页数、下一页链接等）的格式化 JSON 响应，同时 data 键下仍是格式化的资源数组。
- 资源集合类（Resource Collection Class）： 对于更复杂的集合转换逻辑，例如需要在集合级别添加额外元数据或进行集合范围内的转换，可以创建独立的资源集合类（例如 TestCollection extends ResourceCollection）。但在大多数简单场景下，Resource::collection() 已足够。
- 一致性： 保持 API 响应格式的一致性是构建高质量 API 的关键。使用资源可以极大地简化这一过程，确保您的 API 始终以可预测的结构返回数据。
总结
通过本文，我们学习了如何在 Laravel 应用中，利用 API 资源有效地管理 index 方法返回的数据集合。核心在于理解并正确应用 Resource::collection() 方法，它确保了所有返回的 Eloquent 模型都能按照预期的 JSON 结构进行格式化，从而提供了一个结构清晰、易于消费的 API 接口。掌握这一技巧，将有助于您构建更健壮、更专业的 Laravel API。
