README

此包是为Laravel框架构建的，帮助您根据json:api格式构建REST API。它充当API与Eloquent数据库层（Eloquent服务）之间的映射器，同时也支持不需要绑定到数据库的本地数据（本地服务）。

[[目录]]

特性

该包提供处理资源和服务资源集合的方法，同时也提供处理创建、更新和删除请求的方法。

每个资源都支持

• 请求头验证
• 请求体验证
• 链接（用于HATEOAS）
• 包含

此外，集合还支持

• 分页
• 过滤

该包还支持将JsonApi资源类型绑定到Eloquent模型和JsonApi序列化器的功能。

当前包不支持（欢迎贡献！）

• 创建/更新/删除关系
• 稀疏字段
• 排序

第三方库

对于数据组装，我们使用tobscure/json-api包。

术语

• 序列化器：检索数据并将其序列化为指定格式

基本用法

注册包

要注册包，请将 ApiServer\JsonApi2\Providers\JsonApiServerProvider::class, 添加到您的 config/app.php 文件中的 providers 数组。

构建序列化器

为了以json:api格式构建响应，我们需要一个序列化器，该序列化器接受原始数据并将其序列化为所需格式。

我们为要提供API的每种资源类型创建一个序列化器类。因此，我们创建一个新的目录 app/Serializers/ 并将我们的序列化器类放入其中。

该包已经提供了一个抽象的BasicSerializer，您可以用它作为创建自己的序列化器的框架。

UserSerializer.php

class UserSerializer extends BaseSerializer
{
    protected $type = 'user';

    public function getAttributes($user, array $fields = null)
    {
        if (! ($user instanceof User)) {
            throw new \InvalidArgumentException(
                get_class($this).' can only serialize instances of '.User::class
            );
        }

        return parent::getAttributes($model, $fields);
    }

    public function getLinks($user) {
        $links = [
            'key' => 'value',
        ];

        return $links;
    }

    protected function role($user)
    {
        return $this->hasOne($user, RoleSerializer::class);
    }

    protected function permissions($user)
    {
        return $this->hasMany($user, PermissionSerializer::class);
    }
}

绑定资源类型

在许多地方，该包充当数据源（本地、Eloquent）和输出格式之间的映射器。为了自动化这些映射，我们需要将JsonApi类型绑定到模型和序列化器。这最好在单独的服务提供器中完成。

JsonApiResolveServiceProvider.php

class JsonApiResolveServiceProvider extends ServiceProvider
{
    public function register()
    {
        // nothing to do
    }

    public function boot()
    {
        $resolveService = app(ResolveService::class);
        $resolveService->addBinding(
            new ResolveBinding(
                'user',                // type
                UserSerializer::class,  // serializer
                User::class             // model (if type is bound to the database)
            )
        );
    }
}

提供资源

通常，我们会在控制器中有一个显示方法来提供资源

public function show(Request $request, $id) {
    // code for serving resource
}

要提供Eloquent资源，请添加以下内容

$jsonApiResourceService = new EloquentResourceService(
    User::query(),
    $id,
    $request
);

return $jsonApiResourceService->buildResponse();

如果您愿意，可以将 $id 参数设置为 null，并将您需要的任何约束添加到传递给第一个参数的查询构建器中。构建查询后，服务将调用 firstOrFail 来获取资源。

提供资源集合

通常，我们会在控制器中有一个索引方法来提供集合

public function index(Request $request) {
    // code for serving collection
}

要提供本地Laravel集合，请添加以下内容

$jsonApiCollectionService = new NativeCollectionService(
    collect([]),
    $request
);

return $jsonApiCollectionService->buildResponse();

要提供Eloquent集合，只需添加以下内容

$jsonApiCollectionService = new EloquentCollectionService(
    User::query(),
    $request
);

return $jsonApiCollectionService->buildResponse();

如果您对数据库查询有特殊的约束（除了库处理的常用包含和过滤选项外），您只需在将其传递给 EloquentCollectionService 之前将它们添加到查询实例中。

创建资源

待办事项

更新资源

待办事项

删除资源

控制器中删除资源的通常方法如下

public function destroy(Request $request, $id) {
    // code for deleting resource
}

要删除本地资源，我们需要使用回调初始化NativeDeleteService，该回调会在删除时被调用。在回调内部，我们可以执行任何操作以删除资源。

$deleteService = NativeDeleteService(function() {
    $taskService = new TaskService();
    $taskService->removeTask($id);
});
return $deleteService->buildResponse();

要删除Eloquent资源，我们只需像往常一样提供一个查询构建器和标识资源的ID即可。

$deleteService = EloquentDeleteService(
    User::query(),
    $id
);
return $deleteService->buildResponse();

如果您想，可以将$id参数设置为null，并将所需约束添加到第一个参数中传递的查询构建器。构建查询后，服务将调用delete()以删除资源。

深入了解

过滤策略

添加自定义元数据

贡献

提交补丁

可以通过我们gitlab的Merge-Request链接提交补丁。

邮件列表

https://lists.ffnw.de/mailman/listinfo/netmon-dev

许可证

请参阅许可证