LaravelAPI资源统一格式设置方法

你在学习文章相关的知识吗？本文《Laravel API资源统一输出格式方法》，主要介绍的内容就涉及到，如果你想提升自己的开发能力，就不要错过这篇文章，大家要知道编程理论基础和实战操作都是不可或缺的哦！

本文将详细介绍在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() 方法如下：

// 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"
        }
        // ... 更多数据项
    ]
}

注意事项与最佳实践

1. 一致性是关键： 始终使用 Resource::collection() 来处理集合数据，以确保您的 API 响应在返回单个资源和资源集合时保持一致的结构和数据格式。

2. 分页集成： Resource::collection() 同样适用于分页结果。如果您使用 Eloquent 的 paginate() 方法，可以直接将其结果传递给 collection()：

   public function index()
   {
       return TestRessource::collection(Test::paginate(15));
   }

   这将自动包含分页元数据（如 current_page, last_page, total 等）在响应中。

3. 资源集合类： 对于更复杂的集合转换逻辑，您可以创建专门的资源集合类（例如 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 更加健壮和专业。

以上就是《LaravelAPI资源统一格式设置方法》的详细内容，更多关于的资料请关注golang学习网公众号！