API资源-资源集合-Laravel(10.x)从入门到精通(十九)

当前位置:　首页>> 技术小册>> Laravel(10.x)从入门到精通(十九)

### 章节：API资源-资源集合

在Laravel这一强大的PHP框架中，API资源（API Resources）是Laravel 8引入的一个重要特性，旨在简化数据转换到JSON格式的过程，同时允许开发者对输出数据进行细粒度的控制。随着Laravel版本的更新迭代，这一功能在Laravel 10.x中得到了进一步的优化和扩展，特别是资源集合（Resource Collections）的使用，使得处理复杂数据集合的转换和呈现变得更加高效和灵活。

#### 一、理解资源集合的必要性

在构建RESTful API时，经常需要返回一系列的资源（如文章列表、用户集合等）。如果仅依赖单个资源转换，那么对于每个资源实例，你都需要编写相同的转换逻辑，这不仅繁琐而且难以维护。资源集合正是为了解决这一问题而设计的，它允许你定义一次转换逻辑，然后自动应用于集合中的每一个资源实例。

#### 二、创建资源集合

在Laravel 10.x中，创建资源集合通常涉及两个步骤：首先，定义资源类（如果需要的话），然后创建资源集合类。

##### 2.1 定义资源类（可选）

虽然资源集合可以独立于资源类存在，但在实际应用中，通常先定义资源类以封装单个资源的转换逻辑。例如，如果你有一个`Post`模型，你可能会创建一个`PostResource`资源类来定义如何将`Post`实例转换为JSON格式。

```php
// app/Http/Resources/PostResource.php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'content' => $this->content,
            'created_at' => $this->created_at->toDateTimeString(),
            'author' => new UserResource($this->whenLoaded('author')),
        ];
    }
}
```

##### 2.2 创建资源集合类

接下来，你可以为`Post`资源创建一个集合类。Laravel提供了一个基类`ResourceCollection`，你可以通过继承它来创建自己的资源集合类。

```php
// app/Http/Resources/PostCollection.php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class PostCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return [
            'data' => $this->collection->map(function ($post) {
                return new PostResource($post);
            }),
            'links' => [
                'self' => 'link-value', // 根据实际情况填写
            ],
            'meta' => [
                'count' => $this->collection->count(),
            ],
        ];
    }

/**
     * Customize the outgoing response for the resource.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Illuminate\Http\Response  $response
     * @return void
     */
    public function withResponse($request, $response)
    {
        // 这里可以添加自定义的响应头或修改状态码等
    }
}
```

在上面的例子中，`PostCollection`类通过`map`方法遍历集合中的每个`Post`实例，并将它们转换为`PostResource`实例。同时，你还可以在集合级别添加额外的元数据（如分页信息、总数统计等）和链接信息。

#### 三、使用资源集合

一旦你定义了资源集合类，你就可以在控制器中轻松地使用它了。假设你有一个`PostController`，用于处理与`Post`相关的API请求。

```php
// app/Http/Controllers/Api/V1/PostController.php

namespace App\Http\Controllers\Api\V1;

use App\Models\Post;
use App\Http\Resources\PostCollection;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class PostController extends Controller
{
    public function index(Request $request)
    {
        $posts = Post::with('author')->paginate(15); // 假设使用分页

return new PostCollection($posts);
    }
}
```

在上面的控制器方法中，我们首先从数据库中检索`Post`模型的实例集合（可能包括分页），然后直接返回一个新的`PostCollection`实例。Laravel会自动处理将集合转换为JSON格式的工作，并应用你在`PostCollection`类中定义的转换逻辑。

#### 四、高级用法

##### 4.1 条件性加载资源

有时，你可能需要根据请求的不同而加载不同的关联数据。Laravel资源集合允许你在转换过程中动态地加载关联数据。

```php
public function toArray($request)
{
    if ($request->wants('author')) {
        $this->collection->load('author');
    }

return [
        'data' => $this->collection->map(function ($post) {
            return new PostResource($post);
        }),
        // 其他元数据...
    ];
}
```

##### 4.2 自定义响应头和状态码

通过重写`withResponse`方法，你可以为资源集合的响应添加自定义的HTTP响应头或修改状态码。

```php
public function withResponse($request, $response)
{
    $response->header('X-Custom-Header', 'Value');

if ($this->resource instanceof SomeSpecialResource) {
        $response->setStatusCode(202);
    }
}
```

##### 4.3 过滤和排序集合

虽然资源集合本身不直接提供过滤和排序功能，但你可以在将集合传递给资源类之前，在控制器中对其进行处理。

```php
public function index(Request $request)
{
    $posts = Post::query();

if ($request->has('sort_by')) {
        $posts->orderBy($request->input('sort_by'), $request->input('sort_direction', 'asc'));
    }

$posts = $posts->paginate(15);

return new PostCollection($posts);
}
```

#### 五、总结

Laravel 10.x中的API资源集合提供了一种优雅的方式来处理和呈现复杂的数据集合。通过定义资源集合类，你可以将转换逻辑集中管理，并在集合级别添加元数据、链接和自定义响应行为。这不仅提高了代码的可维护性，还使得API的输出更加灵活和强大。在构建RESTful API时，合理利用资源集合将大大提升你的开发效率和API的用户体验。

该分类下的相关小册推荐：

Yii2框架从入门到精通(中)

PHP合辑4-字符串函数

Workerman高性能框架-GatewayWorker

Magento零基础到架构师(系统管理)

Laravel(10.x)从入门到精通(二)

Laravel(10.x)从入门到精通(十二)

Laravel(10.x)从入门到精通(十三)

Laravel(10.x)从入门到精通(十七)

PHP底层原理及源码分析

HTTP权威指南

PHP程序员的设计模式

PHP合辑1-基础入门