Laravel & Lumen RESTFul API 扩展包:Dingo API(三) —— Response(响应)

一个API的功能主要是获取请求并返回响应给客户端,响应的格式是多样的,比如JSON,返回响应的方式也是多样的,这取决于当前构建的API的复杂度以及对未来的考量。

返回响应最简单的方式是直接从控制器返回数组或对象,但不是每个响应对象都能保证格式正确,所以你要确保它们实现了ArrayObject或者Illuminate\Support\Contracts\ArrayableInterface接口:

class UserController
{
    public function index()
    {
        return User::all();
    }
}

在本例中,User类继承自Illuminate\Database\Eloquent\Model,这意味着返回的是可以被格式化为数组的数据,当然也可以返回单个用户:

class UserController
{
    public function show($id)
    {
        return User::findOrFail($id);
    }
}

Dingo API会自动将响应格式化为JSON格式并设置Content-Type头为application/json

1、响应构建器

响应构建器提供了平滑的接口以便我们轻松构建更多自定义的响应。响应构建器通常与转换器(Transformer)一起使用。

要使用响应构建器控制器需要使用Dingo\Api\Routing\Helpers trait,为了让每个控制器都可以使用这个trait,我们将其放置在API基类控制器Controller中:

use Dingo\Api\Routing\Helpers;
use Illuminate\Routing\Controller;

class BaseController extends Controller
{
    use Helpers;
}

现在可以定义一个继承自该控制器的控制器,在这些控制器中可以通过$response属性来访问响应构建器。

数组响应

class UserController extends BaseController
{
    public function show($id)
    {
        $user = User::findOrFail($id);

        return $this->response->array($user->toArray());
    }
}

单个Item响应

class UserController extends BaseController
{
    public function show($id)
    {
        $user = User::findOrFail($id);

        return $this->response->item($user, new UserTransformer);
    }
}

集合响应

class UserController extends BaseController
{
    public function index()
    {
        $users = User::all();

        return $this->response->collection($users, new UserTransformer);
    }
}

分页响应

class UserController extends BaseController
{
    public function index()
    {
        $users = User::paginate(25);

        return $this->response->paginator($users, new UserTransformer);
    }
}

无内容响应

return $this->response->noContent();

创建响应

return $this->response->created();

还可以将位置信息作为创建资源的第一个参数:

return $this->response->created($location);

错误响应

你可以使用多种内置错误生成错误响应:

// A generic error with custom message and status code.
return $this->response->error('This is an error.', 404);

// A not found error with an optional message as the first parameter.
return $this->response->errorNotFound();

// A bad request error with an optional message as the first parameter.
return $this->response->errorBadRequest();

// A forbidden error with an optional message as the first parameter.
return $this->response->errorForbidden();

// An internal error with an optional message as the first parameter.
return $this->response->errorInternal();

// An unauthorized error with an optional message as the first parameter.
return $this->response->errorUnauthorized();

添加额外的响应头

使用了上述方法之后还可以通过添加响应头来自定义响应:

return $this->response->item($user, new UserTransformer)->withHeader('X-Foo', 'Bar');

添加元数据

某些转化层可能会使用元数据(meta data),这在你需要提供额外与资源关联的数据时很有用:

return $this->response->item($user, new UserTransformer)->addMeta('foo', 'bar');

还可以设置元数据数组替代多个方法链的调用:

return $this->response->item($user, new UserTransformer)->setMeta($meta);

设置响应状态码

return $this->response->item($user, new UserTransformer)->setStatusCode(200);

2、自定义响应格式

安装配置中我们已经简单接触过响应格式,默认情况下Dingo API会自动使用JSON格式并设置相应的Content-Type头。除了JSON之外还有一个JSONP格式,改格式会将响应封装到一个回调中。要注册改格式只需要简单将配置文件(Laravel)或启动文件(Lumen)中的默认JSON格式替换成JSONP即可:

'formats' => [
    'json' => 'Dingo\Api\Http\Response\Format\Jsonp'
]

或者:

Dingo\Api\Http\Response::addFormatter('json', new Dingo\Api\Http\Response\Format\Jsonp);

默认情况下回调参数默认查询字符串是callback,这可以通过修改构造函数的第一个参数来设置。如果查询字符串不包含任何参数将会返回JSON响应。

你还可以注册并使用自己需要的响应格式,自定义的格式对象需要继承自Dingo\Api\Http\Response\Format\Format类,同时还要实现如下这些方法:formatEloquentModel, formatEloquentCollection, formatArray 以及 getContentType

3、Morphing 和 Morphed 事件

在Dingo API发送响应之前会先对该响应进行转化(morph),这个过程包括运行所有转换器(Transformer)以及通过配置的响应格式发送响应。如果你需要控制响应如何被转化可以使用ResponseWasMorphedResponseIsMorphing事件。

我们在app/Listeners中为事件创建监听器:

use Dingo\Api\Event\ResponseWasMorphed;

class AddPaginationLinksToResponse
{
    public function handle(ResponseWasMorphed $event)
    {
        if (isset($event->content['meta']['pagination'])) {
            $links = $event->content['meta']['pagination']['links'];

            $event->response->headers->set(
                'link',
                sprintf('<%s>; rel="next", <%s>; rel="prev"', $links['links']['next'], $links['links']['previous'])
            );
        }
    }
}

然后通过在EventServiceProvider中注册事件及其对应监听器来监听该事件:

protected $listen = [
    'Dingo\Api\Event\ResponseWasMorphed' => [
        'App\Listeners\AddPaginationLinksToResponse'
    ]
];

现在所有包含分页链接的响应也会将这些链接添加到Link头。

注意:目前该功能还在开发阶段,不建议用于生产环境。

学院君

学院君 has written 548 articles

资深PHP工程师,Laravel学院院长