README

mattjanssen/api-response-bundle 是一个略微有观点的 Symfony 扩展包，用于将控制器操作的返回值和异常转换为标准化的 JSON 响应。序列化器和 CORS 头可以全局配置，也可以通过注解按路径和操作配置。

安装

通过 Composer

$ composer require mattjanssen/api-response-bundle

启用

在内核中启用该扩展包

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = [
        // ...
        new MattJanssen\ApiResponseBundle\ApiResponseBundle(),
    ];
}

配置

api_response:
    defaults:
        serializer: json_encode
        serialize_groups: []
        cors_allow_origin_regex: https://.*\.mydomain\.com
        cors_allow_headers: [Authorization, Content-Type]
        cors_max_age: 86400
    paths:
        somename:
            prefix: /api/v1/
            serializer: jms_serializer
        othername:
            pattern: ^/api/v[2-4]/
            cors_allow_origin_regex: .*

序列化器可以是空的，'array'，'json_encode'，'json_group_encode'，'jms_serializer'，或者实现 SerializerAdapterInterface 的服务的名称。默认为 'json_encode'。

使用方法

在您的 API 控制器中，只需返回您希望在响应中序列化的任何内容。ApiResponseBundle 将负责将其转换为实际的 JSON 响应。

return [
    'id' => 5,
    'school' => $school,
    'users' => $users,
];

这将产生以下 JSON 返回

{
    data: {
        id: 5,
        school: ...,
        users: [ ... ]
    },
    error: null
}

状态码

默认情况下，响应会发送带有 200 OK 状态。为了使用不同的状态，请在控制器操作上使用 @ApiResponse 注解。这应该仅用于更改成功状态码。有关处理错误输出的信息，请参阅错误响应部分。

/**
 * @ApiResponse(httpCode=201)
 */
public function createAction() {}

产生的响应将具有 201 创建状态。

错误响应

要返回错误，抛出任何实现 ApiResponseExceptionInterface 的异常。在异常中，您可以可选地设置 HTTP 状态码、异常代码、异常消息和要序列化到响应中的错误数据。

throw (new ApiResponseException())
    ->setHttpStatusCode(404)
    ->setCode(100404)
    ->setMessage('Could not find school.')
    ->setErrorData(['schoolId' => 42]);

这将产生以下带有 404 HTTP 状态的 JSON 返回

{
    data: null,
    error: {
        code: 100404,
        message: 'Could not find school.',
        errorData: {
            schoolId: 42
        }
    }
}

异常处理

除了将 ApiResponseExceptionInterface 异常转换为错误响应外，该扩展包还将以下方式处理任何未捕获的异常

HttpExceptionInterface

异常状态码用于响应 HTTP 状态码和错误代码。错误消息是对应的 Response::$statusTexts 数组值。错误数据为 null。

AuthenticationException

响应 HTTP 状态码和错误代码都是 401。错误消息是 "未经授权"。错误数据为 null。

AccessDeniedException

响应 HTTP 状态码和错误代码都是 403。错误消息是 "禁止"。错误数据为 null。

所有其他异常

响应 HTTP 状态码和错误代码都是 500。

如果 Symfony 内核 不在调试模式下，错误消息是 "内部服务器错误"。错误数据为 null。

如果 Symfony 内核 在调试模式下，错误消息是由异常类、消息、文件和行号编译而成的。错误数据是异常跟踪。

测试

$ composer install --dev
$ vendor/bin/phpunit

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅 许可证文件。