README

此包提供了一种管理和处理JSON API错误响应的简单方法。

安装

您可以通过composer安装此包

composer require 3sidedcube/laravel-api-errors

用法

生成API错误响应有两种方式

API错误异常

此包提供了一个名为 ApiErrorException 的异常，您可以根据需要进行扩展。有三个方法可以设置（其中两个是必需的）

• code() - 这是一个表示错误代码的短字符串（必需）。
• message() - 一个提供更多错误详情的易读消息（必需）。
• statusCode() - 错误响应的HTTP状态码。默认设置为400，是可选的。

一旦您有了异常，您可以使用 fromException() 方法生成API错误响应

use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;
use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;

class UserBannedException extends ApiErrorException
{
    /**
     * A short error code describing the error.
     *
     * @return string
     */
    public function code(): string
    {
        return 'user_account_banned';
    }

    /**
     * A human-readable message providing more details about the error.
     *
     * @return string
     */
    public function message(): string
    {
        return 'User account banned.';
    }

    /**
     * The api error status code.
     *
     * @return int
     */
    public function statusCode(): int
    {
        return 403;
    }
}

$exception = new UserBannedException();

// This will return an instance of JsonResponse
$response = ApiErrorResponse::fromException($exception);

自动返回此响应会生成以下JSON响应

{
    "error": {
        "code": "user_account_banned",
        "message": "User account banned."
    }
}

自动返回异常响应

如果您想自动从异常返回JSON响应，您可以将异常添加到 app/Exceptions/Handler.php 中的 $dontReport 数组，如下所示

use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;

protected $dontReport = [
    ApiErrorException::class,
];

直接传递数据

或者您可以使用 create() 方法创建API错误响应

use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;

// This will return an instance of JsonResponse
$response = ApiErrorResponse::create('user_account_banned', 'User account banned.', 403);

自动返回此响应会生成以下JSON响应

{
    "error": {
        "code": "user_account_banned",
        "message": "User account banned."
    }
}

附加数据

如果您想向响应传递额外的“元数据”，可以使用 meta() 方法或将数组传递给create方法，如下所示

use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;
use ThreeSidedCube\LaravelApiErrors\Exceptions\ApiErrorException;

class UserBannedException extends ApiErrorException
{
    /**
     * A short error code describing the error.
     *
     * @return string
     */
    public function code(): string
    {
        return 'user_account_banned';
    }

    /**
     * A human-readable message providing more details about the error.
     *
     * @return string
     */
    public function message(): string
    {
        return 'User account banned.';
    }

    /**
     * The api error status code.
     *
     * @return int
     */
    public function statusCode(): int
    {
        return 403;
    }
    
    /**
     * Any additional metadata to be included in the response.
     *
     * @return array
     */
    public function meta(): array
    {
        return [
            'foo' => 'bar',
        ];
    }
}

$exception = new UserBannedException();

// This will return an instance of JsonResponse
$response = ApiErrorResponse::fromException($exception);

或

use ThreeSidedCube\LaravelApiErrors\ApiErrorResponse;

// This will return an instance of JsonResponse
$response = ApiErrorResponse::create('user_account_banned', 'User account banned.', 403, ['foo' => 'bar']);

自动返回此响应会生成以下JSON响应

{
    "error": {
        "code": "user_account_banned",
        "message": "User account banned.",
        "meta": {
            "foo": "bar"
        }
    }
}

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近有哪些更改。

贡献

请参阅 CONTRIBUTING 了解详细信息。

致谢

• Ben Sherred
• 所有贡献者

许可

Laravel API Errors 是开源软件，采用 MIT 许可证。