README

一个用于在JSON格式中结构化API异常响应的Laravel/Lumen包，遵循https://jsonapi.fullstack.org.cn/。

安装

通过Composer

$ composer require lalu/jer

Laravel

完成安装后，您需要在您的config/app.php中的providers数组中添加服务提供者，如下所示

'providers' => [
    // ...
    LaLu\JER\JERServiceProvider::class,
]

如果您想使用别名，也可以在app.php配置文件中，在aliases数组下，您可能需要添加如下facades

'aliases' => [
    // ...
    'JER' => LaLu\JER\Facades\JERFacade::class
]

然后，通过运行以下命令发布本地化

php artisan vendor:publish

Lumen

打开bootstrap/app.php并添加此行

$app->register(LaLu\JER\JERServiceProvider::class);

如果您想使用别名，也请确保在您的bootstrap/app.php中取消注释

$app->withFacades();

然后，添加此行

class_alias(LaLu\JER\Facades\JERFacade::class, 'JER');

对于本地化，您需要在resources/lang/vendor/lalu-jer/en下创建messages.php文件（默认为en - 英语）。所有内置消息ID都在这里

用法

在app\Exceptions\Handler.php中，让类继承LaLu\JER\ExceptionHandler。

use LaLu\JER\ExceptionHandler;

class Handler extends ExceptionHandler
{
    // ...
}

然后，所有的异常都将由这个包来处理。

您也可以使用abort或throw new \Exception\You\Want()来引发和响应异常。

高级

是否将meta添加到响应JSON中？这并不是什么大问题。

use LaLu\JER\ExceptionHandler;

class Handler extends ExceptionHandler
{
    public $meta = [
        'meta_field_1' => 'meta_value_1',
        // ...
    ];

    // ...
}

或者

use LaLu\JER\ExceptionHandler;

class Handler extends ExceptionHandler
{
    public function beforeRender($request, Exception $exception)
    {
        $this->meta = [
            'meta_field_1' => 'meta_value_1',
            // ...
        ];
    }

    // ...
}

使用beforeRender，它将在render方法之前触发，您可以在此处进行更多逻辑设置以设置meta、headers等。

如果您想自定义某些异常类的响应，只需覆盖getExceptionError。

use LaLu\JER\ExceptionHandler;
use LaLu\JER\Error;

class Handler extends ExceptionHandler
{
    // ...

    /**
     * Get exception jsonapi data.
     *
     * @param \Exception $exception
     *
     * @return array
     */
    protected function getExceptionError(Exception $exception)
    {
        if ($exception instanceof \Exception\You\Want) {
            // status must be an integer and is a HTTP error status code
            $status = 400;
            // headers must be an array of key value
            $headers = [];
            $content = [
                'title' => 'Your exception custom title',
                'detail' => 'Your exception custom detail',
            ];
            // error can be an instance/array items of \LaLu\JER\Error or array of error array
            $error = new Error(['version' => $this->jsonapiVersion], $content);
            $error->status = '400';
            // ...
            return [$status, $error, $headers];
        } elseif ($exception instanceof \Other\Exception) {
            return [400, [['title' => 'Your request is bad request']], []];
        } else {
            return parent::getExceptionError($exception);
        }
    }
}

如果您想自定义错误JSON响应，请随意使用此函数

$option = [
    'version' => '1.0', // JSONAPI specification version
    'status' => 400, // HTTP status code
    'headers' => ['My-Custom-Header' => 'Value'], // Response headers,
    'exception' => new \Exception(), // Exception
];
$attributes = [
    'meta' => [
        'apiVersion' => '1.0.0',
        'author' => 'thanh-taro',
    ],
    'errors' => new Error(['version' => '1.0'], ['title' => 'My custom error', 'detail' => 'This is an error response']), // Error content
];
$response = \JER::getResponse($option, $attributes);

请注意，JER是一个别名，如果您没有配置别名，您可能可以使用

(new \LaLu\JER\JsonExceptionResponse())->getResponse($option, $attributes);

许可证

MIT许可证（MIT）。