Laravel中的JSON API资源的构建及使用

在Laravel中构建API是我的热情所在，我花了很多时间寻找完美的方式来返回一致的JSON:API友好资源，以便我可以找到并使用标准。

过去，我使用了一个拼凑而成的解决方案，几乎可以实现我所需要的，但这是一项相当多的工作。

这种方法的负面影响超过了好处，因为实现它所花费的开发时间感觉不值得。

幸运的是，Tim MacDonald 为这个用例构建了一个很棒的包。

它允许我们构建和返回易于使用的 JSON:API 兼容资源。

让我们来看看它是如何工作的。

通常在构建API资源时，我们会扩展LaravelJsonResource或CollectionResource取决于我们想要实现的目标。

我们的典型资源可能如下所示：

class PostResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'type' => 'post',
            'attributes' => [
                'title' => $this->title,
                'slug' => $this->slug,
                'content' => $this->content,
            ]
        ];
    }
}

我们正在添加一个简单的实现来“伪造”一个基本级别的 JSON:API 资源。

但正如你所看到的，这有点 - 糟糕。

让我们安装 Tim 的软件包：

composer require timacdonald/json-api

现在我们可以重构上述资源以遵循 JSON:API 标准。

让我带你了解这些变化。

首先，我们需要将扩展的类更改JsonResource为JsonApiResource：

class PostResource extends JsonApiResource

我们需要确保我们更改的下一件事是删除该toArray方法，

因为这个包将在后台为您处理这个 - 相反，我们使用对 JSON:API 标准有用的不同方法。

例如，要添加attributes到您的资源，您可以使用以下方法：

protected function toAttributes(Request $request): array
{
return [
'title' => $this->title,
                'slug' => $this->slug,
                'content' => $this->content,
];
}

现在让我们看看关系。

以前我们会做类似的事情：

 return [
    'id' => $this->id,
    'type' => 'post',
    'attributes' => [
    'title' => $this->title,
    'slug' => $this->slug,
    'content' => $this->content,
],
'relationships' => [
    'category' => new CategoryResource(
    resource: $this->whenLoaded('category'),
    ),
]
];

无论如何，这都不是一个坏方法。

但是，让我们看看如何将这些添加到 JSON:API 包中：

protected function toRelationships(Request $request): array
{
    return [
        'category' => fn () => new CategoryResource(
        resource: $this->category,
        ),
    ];
}

所以这一次，我们通过一个闭包进行评估以返回关系。

这是一种非常强大的方法，因为它使我们可以向关系加载添加非常自定义的行为——这意味着我们可以加载不同的条件关系或在资源上运行授权。

需要注意的另一点是，仅在客户端包含关系时才评估闭包 - 使其更清晰。

更进一步，添加指向您的 API 资源的链接是我认为重要的一步。

添加这些链接使您的 API 可导航，允许客户端根据需要以编程方式跟踪链接。

以前我会添加另一个数组条目来添加这些，并使用route助手来回显这些。

JSON:API 包有另一种方法，特别流畅：

protected function toLinks(Request $request): array
{
    return [
    Link::self(route('api:v1:posts:show', $this->resource)),
    ];
}

如您所见 - 它流畅、简单，并且会为您生成正确的链接。

当然，欢迎您在此处添加您需要的内容，但它会以 JSON:API 标准化方式添加链接 - 所以您不必这样做。

最后，元数据，在 JSON:API 中，您可以在其中添加其他信息，meta-object以便您可以添加文档链接或您可能需要通过 API 资源传回的任何内容（取决于您的 API 设计）。

没有一百万个用例，但该软件包确实支持它。

因此，让我们看一下以了解它。

protected function toMeta(Request $request): array
{
    return [
        'depreciated' => false,
        'docs' => 'https://docs.domain/com/resources/posts',
    ];
}

正如您在上面看到的，我们可以添加折旧警告，以便客户可以收到他们需要考虑更改的资源的通知 - 以及解释替换方法的文档链接。

您如何构建 API 资源？您是否遵循任何特定标准？在推特上告诉我们！

转：

https://laravel-news.com/json-api-resources-in-laravel