小白折腾服务器（七）：自定义接口错误响应格式

aen233 的个人博客 / 5 / 17 / 创建于 5年前 / 更新于 5年前

上一篇是使用后置中间件自定义接口成功返回格式
这篇来写处理异常，自定义接口错误返回格式

基础小知识
laravel处理异常的位置在 app/Exceptions 这个目录，如果新建异常类，就在这个目录
这个目录中，最重要的是 Handler.php 这个文件，如何处理渲染异常，是这个类的rander方法。如果你需要自定义错误输出，其实就是重写这个rander方法。

leo老师在电商实战那本书里第5.7节-优雅地处理异常里面教过，

Laravel 5.5 之后支持在异常类中定义 render() 方法，该异常被触发时系统会调用 render() 方法来输出，我们在 render() 里判断如果是 AJAX 请求则返回 JSON 格式的数据，否则就返回一个错误页面。

这就是说，我们只要新建一个 xxxException 类，让它继承自 Exception ,
在这个 xxxException 类中，定义一个构造函数，用来接收参数（如$message, $code），
再定义一个render方法，处理接收的参数，组装成你想要的格式（如$content = ['message' => $this->message, 'code' => $this->code]）,最后返回return response()->json($content, $status);，$content就是你自定义的异常输出内容，$status是http状态码。
然后在控制器方法中，throw new xxxException('message',500)。试一下，就是你自定义的错误格式了。
可以新建多个异常类，用来输出不同的异常。
最简单的异常类：

namespace App\Exceptions;

use Exception;

class SimpleException extends Exception
{
    const HTTP_OK = 200;
    const HTTP_ERROR = 500;

    protected $data;

    public function __construct($message, int $code = self::HTTP_OK, array $data = [])
    {
        $this->data = $data;
        parent::__construct($message, $code);
    }

    public function render()
    {
        $content = [
            'message'   => $this->message,
            'code'      => $this->code,
            'data'      => $this->data ?? [],
            'timestamp' => time()
        ];

        $status = self::HTTP_ERROR;

        return response()->json($content, $status);
    }
}

如果不想新建异常类，只需要统一异常错误输出，就修改app/Exceptions/Handler中的render方法就好了。

    public function render($request, Exception $exception)
    {
      //  这里通常要用到 instanceof 这个运算符，先判断再处理
      //  return parent::render($request, $exception);   注释掉这行
      return  response()->json($exception->getMessage(), 500);
    }

做个小总结，自定义错误处理有两个方法（其实都一样）
1.新建一个异常类，在app/Exceptions/Handler中的render方法将所有异常都指向你新建的异常类。
2.直接修改app/Exceptions/Handler中的render方法，自定义异常格式。

第一种：BaseException

BaseException是一个很灵活的异常类，可以自定义多种参数。

在app/Exceptions下新建BaseException

namespace App\Exceptions;

use Exception;

class BaseException extends Exception
{
    const HTTP_OK = 200;

    protected $data;

    protected $code;

    public function __construct($data, int $code = self::HTTP_OK, array $meta = [])
    {
        // 第一个参数是data，是因为想兼容string和array两种数据结构
        // 第二个参数默认取200，是因为公司前端框架限制，所以是status取200，错误码用code表示
        // 如果第二个参数是任意httpStatus（如200，201，204，301，422，500），就只返回httpStatus，如果是自定义错误编码，（如600101，600102），就返回httpstatus为200，返回体中包含message和code。
        // 第三个参数默认为空数组，如果在message和code之外，还需要返回数组，就传递第三个参数
        $this->data = $data;
        $this->code = $code;
        $this->meta = $meta;
//        parent::__construct($data, $code);
    }

    public function render()
    {
        $httpStatus = getHttpStatus();
        $status  = in_array($this->code, $httpStatus) ? $this->code : self::HTTP_OK;
        $content = [];
        if (is_array($this->data)) {
            $content = $this->data;
        }
        if (is_string($this->data)) {
            $content = in_array($this->code, $httpStatus)
                ? [
                    'message' => $this->data
                ]
                : [
                    'message' => $this->data,
                    'code'    => $this->code,
                    //                    'timestamp' => time()
                ];
        }

        if ($this->meta) {
            $content = array_add($content, 'meta', $this->meta);
        }

        return response($content, $status);
    }
}

在helpers中增加函数：（或者直接写在这个异常类中，私有调用）
该函数是获取Symfony定义的所有Http状态码。比如200=HTTP_OK。
```
function getHttpStatus()
{
$objClass = new \ReflectionClass(\Symfony\Component\HttpFoundation\Response::class);
// 此处获取类中定义的全部常量 返回的是 [key=>value,...] 的数组,key是常量名,value是常量值
return array_values($objClass->getConstants());
}
```
3.基础使用

baseException($data, int $code=200, array $meta=[]);
第1个参数可以为string 或 array.
第2个参数默认为200，如果传的code是任意一个httpStatus，表示返回的http状态码（如404、500等），
如果是自定义错误码（非任意一个httpStatus，如1001、1002），则http状态码返回200，code码在json内容中返回
第3个参数默认为空数组。如果传第3个参数，将一起返回。

3.1 参数传string

throw new BaseException('都是好孩子');

Status: 200 OK 
{
    "message": "都是好孩子"
}

3.2 参数传string,code(自定义错误码，非httpStatus)

throw new BaseException('都是好孩子',1001);

Status: 200 OK 
{
    "message": "都是好孩子",
    "code": 1001
}

3.3 参数传string,code（httpStatus）

throw new BaseException('都是好孩子', 404);

Status: 404 Not Found
{
    "message": "都是好孩子"
}

3.4 参数传array

throw new BaseException(['msg' => '都是好孩子', 'code' => '123']);

Status: 200 OK
{
    "msg": "都是好孩子",
    "code": "123"
}

3.5 参数传array，code（httpStatus）

throw new BaseException(['msg' => '都是好孩子', 'code' => '123'], 403);

Status: 403 Forbidden
{
    "msg": "都是好孩子",
    "code": "123"
}

3.6 参数传string，code（httpStatus），array

throw new BaseException('都是好孩子', 422, ['msg' => '天是蓝的', 'code' => '24678']);

Status: 422 Unprocessable Entity
{
    "message": "都是好孩子",
    "meta": {
        "msg": "天是蓝的",
        "code": "24678"
    }
}

3.7 参数传string，code（自定义错误码，非httpStatus），array

throw new BaseException('都是好孩子', 4567, ['msg' => '天是蓝的', 'code' => '24678']);

Status: 200 OK
{
    "message": "都是好孩子",
    "code": 4567,
    "meta": {
        "msg": "天是蓝的",
        "code": “24678"  
    }
}

3.8 参数传array，code（自定义错误码，非httpStatus），array

throw new BaseException(['msg' => '都是好孩子', 'code' => '123'], 1234, ['msg' => '天是蓝的', 'code' => '24678']);

Status: 200 OK
{
    "msg": "都是好孩子",
    "code": "123",
    "meta": {
        "msg": "天是蓝的",
        "code": "24678"
    }
}

3.9 参数传array，code（自定义错误码，非httpStatus），array

throw new BaseException(['msg' => '都是好孩子', 'code' => '123'], 500, ['msg' => '天是蓝的', 'code' => '24678']);

Status: 500 Internal Server Error
{
    "msg": "都是好孩子",
    "code": "123",
    "meta": {
        "msg": "天是蓝的",
        "code": "24678"
    }
}

参数校验异常

使用laravel内置的ValidationException

1.在app/Exceptions/Handler中添加

 public function render($request, Exception $exception)
    {
        //-------新加这4行---------
        if ($exception instanceof ValidationException) {
            $message = current(current(array_values($exception->errors())));
            throw new BaseException($message, 4022); // 不加4022，会返回httpStatus=422;加4022是因为返回前端统一httpStatus为200，就在422中加了0
        }
        //------------------------

        return parent::render($request, $exception);
    }

2.基础使用

    //控制器中，不需要额外抛出异常
    public function index(Request $request)
    {
        Validator::make($request->all(), [
            'file' => 'bail|required|file'
        ], [
            'file.required' => '请上传文件'
        ])->validate();
    }

输出：

    //handler中不加4022
    Status: 422 Unprocessable Entity
    {
        "message": "请上传文件"
    }

    //handler中加4022
    Status: 200 OK
    {
        "message": "请上传文件",
        "code": 4022,
    }

处理其他异常

同参数校验异常，如处理FatalThrowableError(定义错误码为5678)，然后故意写个语法错误。
同样不需要自己抛错，也不会出现报错大黑框

Status: 200 OK
{
    "message": "Parse error: syntax error, unexpected 'dd' (T_STRING)",
    "code": 5678
}

CodeException

为了项目统一规范，需统一管理code错误码，所以建立CodeException。

在app/Exceptions下新建error.php。返回错误信息数组。

<?php
return [
1001 =>'门前大桥下',
1002 =>'游过一群鸭'
];

2 . 在helpers中增加函数：
该函数是获取该errorCode相对应的errorMessage。

function getErrorMessage($code)
{
    $err = require_once __DIR__.'/../app/Exceptions/error.php';
    return $err[$code];
}

3 . 在app/Exceptions下新建CodeException

4 . 基础使用

throw new CodeException(1001);

// 返回
{
    "message": "门前大桥下",
    "code": 1001
}

有附加错误信息数组

throw new CodeException(1001,['info'=>'门前大桥下','text'=>'游过一群鸭']);

//返回
{
    "message": "门前大桥下",
    "code": 1001,
    "data": {
        "info": "门前大桥下",
        "text": "游过一群鸭"
    }
}

第二种修改Handler

public function render($request, Exception $exception)
    {
        if ($exception instanceof BaseException
            || $exception instanceof HttpException
            || $exception instanceof ValidationException
            || $exception instanceof QueryException
            || $exception instanceof ModelNotFoundException
            || $exception instanceof ErrorException
        ) {
            return $this->error($exception);
        }

        return parent::render($request, $exception);
    }

    /**
     * 自定义错误输出
     *
     * @param $exception
     *
     * @return \Illuminate\Http\JsonResponse
     */
    private function error($exception)
    {
        $statusCode = 500;
        if ($exception instanceof ValidationException) {
            $code    = $exception->status;
            $message = current(current(array_values($exception->errors())));
        } else {
            $code    = $exception->getCode() ?: ($exception->statusCode ?? 404);
            $message = $exception->getMessage();
        }

        $response = [
            'id'      => md5(uniqid()),
            'code'    => $code,
            'status'  => $statusCode,
            'message' => $message,
            'error'   => 'ERROR',
        ];

        if ($exception instanceof BaseException && $exception->getData()) {
            $response['data'] = $exception->getData();
        }

        iuLog('error', 'Response Error: ', $response);
        iuLog(PHP_EOL);

        return response()->json($response, $statusCode, [], 320);
    }

这里也保留了BaseException，但是写的要简单些，因为大部分逻辑写在Handler里面，这里只留了获取StatusCode 和获取数组信息。使用和上面一样。

namespace App\Exceptions;

use Exception;

class BaseException extends Exception
{
    protected $data;

    /**
     * Error constructor.
     *
     * @param string $message
     * @param int    $code
     * @param array  $data
     */
    public function __construct($message = "", $code = 500, $data = [])
    {
        $this->data = $data;
        parent::__construct($message, $code);
    }

    public function getStatusCode()
    {
        $objClass = new \ReflectionClass(\Symfony\Component\HttpFoundation\Response::class);
        // 此处获取类中定义的全部常量 返回的是 [key=>value,...] 的数组
        // key是常量名 value是常量值
        // dd($objClass->getConstants());
        $httpStatus = array_values($objClass->getConstants());

        return in_array($this->code, $httpStatus) ? $this->code : 500;
    }

    public function getData()
    {
        return $this->data;
    }
}

本作品采用《CC 协议》，转载必须注明作者和本文链接

本帖由系统于 5年前自动加精

讨论数量: 17

kinyou

课程读者 102 声望 / PHP全栈工程师 @ ABC

认真的人最可爱

5年前评论

aen233

课程读者 399 声望 / php @ abc

@kinyou :relaxed:蟹蟹呀

GuanJie

课程读者 253 声望 / phper @ usitrip

学习了，感谢

guanhui07

见习助教 14 声望 / php高级开发 @ 开发者

返回的字段信息和我差不多

十七岁程序员想当歌手

课程读者 56 声望 / 技术组长 @ 自由职业

你用的是 dingo / api 吗？我这里测试不成功。

@十七岁程序员想当歌手没有用dingo，就是laravel直接orm查询返回和使用aipresoure两种

wploey

课程读者 0 声望

@十七岁程序员想当歌手 https://mikecoder.cn/post/145/ 把 ding/api 的异常改下就可以

node

课程读者 7 声望 / 高级开发工程师 @ 芮欧百货

file 请修正该参数哈哈

哈哈哈，细心

LLLLL1998

0 声望

那个第一种：BaseException 1.里是不是少了个protected $meta。。还有想请教一下就是在xxxException类的render()方法是怎么被调用的。。还像没看到有调用render()方法呀...谢谢

PHP-Coder

好像真的少了

兜兜转转便是空

课程读者 15 声望

CodeException 的代码没贴出来耶

xiaohaima888

file
这里的不加4022应该返回的200的状态码吧，这个不是你在BaseException里面render方法里面定义的吗？怎么会变成422默认的参数验证的状态码呢？

aen233 （楼主）

都可以自己设置的，你想让状态码是200就是200，想让它422就是422

勇敢的心

见习助教 845 声望

我在想那些错误应该按照异常来处理，比如：代码错误、网络超时
还有比如：没有权限、活动结束、库存不足。这些应该是按照异常来处理，还是正常返回

抛出异常的时候，http状态码到底是200还是其他状态

你也可以设置成500，或任意的码，区分清楚code和status就好了

很灵活，你设置成啥就是啥，我代码里面的，如果第二个参数是http状态码，比如403，404，500，就是http状态码，如果第二个参数不是http状态码，就是200。

勇敢的心（作者）

@aen233 我还有个小疑问，代码错误肯定是要抛出异常的，那么库存不足、购买次数达到上限、余额不足这类状态是否也要抛出异常

@海阔天空 throw new BaseException(678001,'库存不足'); 这样status是你设置的200或500，code码是678001

@aen233 如果我要分层，那么判断库存的实在service中，如果库存不足我应该直接再service中批出异常好还是一层层的返回然后在控制器抛出异常好

@海阔天空一层层的返回你累不累啊，laravel代码除非调用外部接口，没必要一堆try catch

@aen233 哦，那就是说如果模型或者service中有错误的操作，可以直接抛出response

@海阔天空可以哒

@aen233 好的，大佬！

@海阔天空我也还是小白，能够帮到你就太好了

@aen233 您说笑了

感觉这个异常类也可以用来返回正确的响应啊

HongXunPan

想法一致就来搜了，蓝后看完了所有文章发现是个宝藏程序员。不知有没有个人网站之类的，翻了一下你的github也没有找到，想交个朋友~~

4年前评论

嘿嘿被夸奖了，谢谢呀。一起加油呀

sunrui318

课程读者 74 声望 / 剑客 @ 缓存

好像发现要给问题，如果使用了作者的自定义返回成功返回格式，和这里的异常统一处理。当 httpStatus 为 200 时，成功返回格式化会对异常返回做格式处理。需要过滤一下：

        /* @var Response $response */
        // 对状态码为 200 且包含异常的返回值兼容
        if($response->exception ?? false) {
            return $response;
        }

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容，与人为善，比聪明更重要！

帮助

小白折腾服务器（七）：自定义接口错误响应格式

第一种：BaseException

参数校验异常

处理其他异常

CodeException

第二种修改Handler

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

小白折腾服务器（七）：自定义接口错误响应格式

第一种：BaseException

参数校验异常

处理其他异常

CodeException

第二种 修改Handler

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

请登录

第二种修改Handler