Laravel & Lumen RESTFul API 扩展包：Dingo API（五） —— 转化器（Transformer）

1、简介

通过转化器，你可以将对象转化为数组，并强制转化整型和布尔类型，包括分页结果和嵌套关联。

本章节我们主要讨论转化器及其使用，这里的转化器包括以下两层意思：

• 转化层（transformation layer）是一个准备和处理转化器的库
• 转化器（transformer）是一个获取原始数据并将其转化为数组格式的类，处理器的处理方式取决于转化层。

2、使用转化器

有多种方式使用转化器。

为某个类注册转化器

当你为某个类注册转化器后就可以从路由返回这个类（假设它可以被转化为数组）并自动经过转化器处理：

app('Dingo\Api\Transformer\Factory')->register('User', 'UserTransformer');

这在使用模型的简单API中很有用，因为你可以从路由中直接返回模型。

使用响应构建器

参考响应构建器章节。

2、Fractal

Fractal是Dingo API默认的转化层，它提供了一系列有用的特性来保持数据的一致性。

使用Fractal之前建议好好阅读其官方文档。

全自动关联关系渴求式加载

当使用Fractal的内置功能嵌入关联关系时确保其命名和模型中的命名一致。扩展包会自动为你渴求式加载这些关联关系。

高级配置

Fractal以默认配置注册为默认转化层，要手动配置需要在服务提供者中实例化Dingo\Api\Transformer\Adapter\Fractal实例：

$this->app['Dingo\Api\Transformer\Factory']->setAdapter(function ($app) {
     return new Dingo\Api\Transformer\Adapter\Fractal(new League\Fractal\Manager, 'include', ',');
});

如果你使用的是Lumen可以在启动文件（bootstrap.php）中这么做：

app('Dingo\Api\Transformer\Factory')->setAdapter(function ($app) {
    return new Dingo\Api\Transformer\Adapter\Fractal(new League\Fractal\Manager, 'include', ',');
});

通过响应构建器实现高级使用

与响应构建器相结合使用Fractal通常是从控制器返回数据的最佳方式。响应构建器上的item、collection和paginator方法都可以接收额外参数用于自定义Fractal。

资源key

return $this->item($user, new UserTransformer, ['key' => 'user']);

使用回调

Fractal转化层允许你注册一个创建资源之后触发的回调，这个回调接收League\Fractal\Resource\Item或者League\Fractal\Resource\Collection作为第一个参数，League\Fractal\Manager实例作为第二个参数。然后你可以使用这个回调在更复杂的层级上与资源进行交互。

最常见的使用案例就是设置分页游标或者修改响应串行：

return $this->collection($users, new UserTransformer, [], function ($resource, $fractal) {
    $resource->setCursor($cursor);
});

如果你不想传递资源key参数可以省略这个空数组：

return $this->collection($users, new UserTransformer, function ($resource, $fractal) {
    $fractal->setSerializer(new CustomSerializer);
});

3、自定义转化层

如果你想对数据转化进行更多的自定义，可以在Dingo API中实现自己的转化层。这需要创建一个实现Dingo\Api\Contract\Transformer\Adapter的类并且实现transform方法：

use Dingo\Api\Http\Request;
use Dingo\Api\Transformer\Binding;
use Dingo\Api\Contract\Transformer\Adapter;

class MyCustomTransformer implements Adapter
{
    public function transform($response, $transformer, Binding $binding, Request $request)
    {
        // Make a call to your transformation layer to transformer the given response.
    }
}

transform是唯一必须的方法，你可以自由添加自己想要的其他方法。transform方法的目的是获取$response，然后和$transformer一起传递给转化层处理，然后转化层会返回一个数组，最终这个数组被transform方法返回。如果你的转化层很简单，可以完全在这个类中实现所有逻辑。

$bindings参数在你的转化层包含更多特性比如添加元数据或者允许开发者通过回调与转化层交互时很有用。

$request参数是当前被执行的HTTP请求，当你的转化层需要查询字符串参数或者其他相关数据时很有用。