wwjpackages/laravel-json-api

提供统一返回格式和错误处理方式

1.0.2 2021-01-22 07:07 UTC

Requires

• php: ^7.0
• illuminate/config: ~5.0|~6.0
• illuminate/http: ^5.1|^6
• illuminate/support: ~5.0|~6.0

Requires (Dev)

• illuminate/console: ^5.1|^6

MIT

README

主要是为了统一前后端 restful api 的返回格式标准，按照 https://jsonapi.org 定义返回指定的数据格式。

安装

从composer安装

composer require wwjpackages/laravel-json-api

添加service provider

in laravel:

在 config/app.php 中的 providers 添加

'providers' => [
    ...
    WwjPackages\JsonApi\Providers\LaravelServiceProvider::class,
]

in lumen:

在 bootstrap/app.php 中添加

$app->register(WwjPackages\JsonApi\Providers\LaravelServiceProvider::class);

发布配置

php artisan vendor:publish --provider "WwjPackages\JsonApi\Providers\LaravelServiceProvider"

使用

Controller

添加一个 trait 给response，ApiHelper包含了4个常用的返回值和status code类型。

分别为 content, noContent, created, accepted

namespace App\Http\Controllers;

use WwjPackages\JsonApi\Traits\ApiHelper;
use Illuminate\Routing\Controller as BaseController;

class Controller extends BaseController
{
    use ApiHelper;

    public function show()
    {
        // do something...
        return $this->content(['foo' => 'bar']);        
    }
    
    public function create()
    {
        // do something...
        return $this->created();
    }
}

Exception

1、命令行创建一个新的 Exception 类

php artisan make:api-exception NotFoundException

2、根据标准修改 http 状态码

class NotFoundException extends BaseApiException
{
    protected $status = 404;
}

3、在 config/errors.php 中配置错误详情

'not_found_user' => [
    'code'   => 10003,
    'detail' => '未找到该用户 {name}',
],

4、抛出自定义异常

throw new NotFoundException('not_found_user', ['name' => 'xiaoming']);

5、重写 app/Exceptions/Handler.php 的render方法

function render($request, Exception $e)
    {
        $rendered = parent::render($request, $e);

        if (config('app.debug')) {
            return $rendered;
        }

        $status = $rendered->getStatusCode();
        $errors = [
            'code'   => 10000,
            'detail' => $e->getMessage(),
            'status' => $status,
        ];

        if ($e instanceOf \WwjPackages\JsonApi\Exceptions\BaseApiException) {
            $errors = $e->toArray();
            $status = $e->getStatus();
        }

        if ($e instanceOf \Symfony\Component\HttpKernel\Exception\NotFoundHttpException) {
            $errors = array_merge([
                'title'  => 'not_found',
                'status' => 404,
            ], config('errors.not_found'));

            $status = 404;
        }

        if ($e instanceOf \Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException) {
            $errors = array_merge([
                'title'  => 'method_not_allowed',
                'status' => 405,
            ], config('errors.method_not_allowed'));

            $status = 405;
        }

        return response()->json(['errors' => $errors], $status);
    }