Laravel 打造适合 API 的异常处理响应格式

Laravel全局捕获异常后,会把异常转为相应的数据格式返回给用户。如果想要规定的数据格式相应,那我们只需重写异常捕获后的处理方法即可。

异常处理流程

Illuminate\Foundation\Exception\Handler 中的 render 方法用来将异常转化为响应。

public function render($request, Exception $e)
{
    if (method_exists($e, 'render') && $response = $e->render($request)) {
        return Router::toResponse($request, $response);
    } elseif ($e instanceof Responsable) {
        return $e->toResponse($request);
    }

    $e = $this->prepareException($e);

    if ($e instanceof HttpResponseException) {
        return $e->getResponse();
    } elseif ($e instanceof AuthenticationException) {
        return $this->unauthenticated($request, $e);
    } elseif ($e instanceof ValidationException) {
        return $this->convertValidationExceptionToResponse($e, $request);
    }

    return $request->expectsJson()
                    ? $this->prepareJsonResponse($request, $e)
                    : $this->prepareResponse($request, $e);
}

render() 中又调用了 prepareException() 对部分异常进行预处理,但并未执行转化为响应的操作。

ModelNotFoundException 一般在模型查找不到抛出,prepareException() 中它被转为 Symfony 包中NotFoundHttpException,默认状态码404;

AuthorizationException 在 Policy 权限未通过时抛出,prepareException() 中它被转为 Symfony 包中 AccessDeniedHttpException,默认状态码403;

TokenMismatchException 在 CSRF 验证未通过时抛出,prepareException() 中它被转为 Symfony 包中 HttpException,给定状态码419;

其他异常直接返回。

protected function prepareException(Exception $e)
{
    if ($e instanceof ModelNotFoundException) {
        $e = new NotFoundHttpException($e->getMessage(), $e);
    } elseif ($e instanceof AuthorizationException) {
        $e = new AccessDeniedHttpException($e->getMessage(), $e);
    } elseif ($e instanceof TokenMismatchException) {
        $e = new HttpException(419, $e->getMessage(), $e);
    }
    return $e;
}

在回到 render() ,预处理异常之后,又分别对 HttpResponseException、AuthenticationException 和 ValidationException 单独处理,并转为响应返回。

除此以外的异常,都在 prepareJsonResponse() 或 prepareResponse() 处理 ,expectsJson() 用来判断返回 json 响应还是普通响应。

修改异常响应格式

了解了异常处理流程,接下来就处理异常响应格式。

修改登录认证异常格式

由上文可知,AuthenticationException 被捕获后,调用 unauthenticated() 来处理。

protected function unauthenticated($request, AuthenticationException $exception)
{
    return $request->expectsJson()
                ? response()->json(['message' => $exception->getMessage()], 401)
                : redirect()->guest($exception->redirectTo() ?? route('login'));
}

在 app\Exceptions\Handler.php 中重写 unauthenticated() 使其返回我们想要的数据格式。

protected function unauthenticated($request, AuthenticationException $exception)
{
    return $request->expectsJson()
        ? response()->json([
            'code' => 0,
            'data' => $exception->getMessage(),
        ], 401)
        : redirect()->guest($exception->redirectTo() ?? route('login'));
}

修改验证异常格式

同样由上文可知,ValidationException 被捕获后交由 convertValidationExceptionToResponse() 处理,进入此方法后我们需要继续追踪,若是需要 json 响应,最终交由 invalidJson() 处理。

protected function convertValidationExceptionToResponse(ValidationException $e, $request)
{
    if ($e->response) {
        return $e->response;
    }

    return $request->expectsJson()
                ? $this->invalidJson($request, $e)
                : $this->invalid($request, $e);
}
protected function invalidJson($request, ValidationException $exception)
{
    return response()->json([
        'message' => $exception->getMessage(),
        'errors' => $exception->errors(),
    ], $exception->status);
}

我们继续在 app\Exceptions\Handler.php 重写 invalidJson() 即可自定义返回格式。

protected function invalidJson($request, ValidationException $exception)
{
    return response()->json([
        'code' => 0,
        'data' => $exception->errors(),
    ], $exception->status);
}

修改其他异常格式

其他异常是调用 prepareJsonResponse() 来处理,此方法又调用 convertExceptionToArray() 来处理响应格式。

protected function prepareJsonResponse($request, Exception $e)
{
    return new JsonResponse(
        $this->convertExceptionToArray($e),
        $this->isHttpException($e) ? $e->getStatusCode() : 500,
        $this->isHttpException($e) ? $e->getHeaders() : [],
        JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
    );
}
protected function convertExceptionToArray(Exception $e)
{
    return config('app.debug') ? [
        'message' => $e->getMessage(),
        'exception' => get_class($e),
        'file' => $e->getFile(),
        'line' => $e->getLine(),
        'trace' => collect($e->getTrace())->map(function ($trace) {
            return Arr::except($trace, ['args']);
        })->all(),
    ] : [
        'message' => $this->isHttpException($e) ? $e->getMessage() : 'Server Error',
    ];
}

在 app\Exceptions\Handler.php 中重写 convertExceptionToArray() 来自定义其他异常响应格式。

protected function convertExceptionToArray(Exception $e)
{
    return config('app.debug') ? [
        'code' => 0,
        'data' => $e->getMessage(),
        'exception' => get_class($e),
        'file' => $e->getFile(),
        'line' => $e->getLine(),
        'trace' => collect($e->getTrace())->map(function ($trace) {
            return Arr::except($trace, ['args']);
        })->all(),
    ] : [
        'code' => 0,
        'data' => $this->isHttpException($e) ? $e->getMessage() : 'Server Error',
    ];
}

强制 json 响应

代码中多次出现了 expectsJson() ,此方法是用来判断返回 json 响应还是普通响应。

public function expectsJson()
{
    return ($this->ajax() && ! $this->pjax() && $this->acceptsAnyContentType()) || $this->wantsJson();
}

以下两种条件下,会返回json响应。

  1. 非XML请求、非pjax并且 Headers 中 Accept 设置为接收所有格式响应;

  2. Headers Accept 设置为 /json、+json。如:Accept:application/json。

除此之外的情况,将不会响应json。我们可以利用中间件强制追加 Accept:application/json,使异常响应时都返回json。(参考教程 L03 6.0 中提到的方法)

创建中间件 AcceptHeader

<?php

namespace App\Http\Middleware;

use Closure;

class AcceptHeader
{
    public function handle($request, Closure $next)
    {
        $request->headers->set('Accept', 'application/json');
        return $next($request);
    }
}

在 app/Http/Kernel.php 中,将中间件加入路由组即可。

protected $middlewareGroups = [
    'web' => [
        .
        .
        .
    'api' => [
        \App\Http\Middleware\AcceptHeader::class,
        'throttle:60,1',
        'bindings',
    ],
];

大功告成。

本作品采用《CC 协议》,转载必须注明作者和本文链接
本帖由系统于 3年前 自动加精
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L04 微信小程序从零到发布》
从小程序个人账户申请开始,带你一步步进行开发一个微信小程序,直到提交微信控制台上线发布。
讨论数量: 17

希望可以有个前因后果 :joy:

3年前 评论
Mr-houzi (楼主) 3年前
colin_king

一库

3年前 评论

好,不错,你直接贴源码,多省事!

3年前 评论

api 这头 我是接管异常 统一返回 200 状态码 返回数据中的code 定义 接口状态码协议

对于异常接管 你可以参考下我这个问答的回复
分享:关于 Laravel 路由缓存的疑惑

3年前 评论
Mr-houzi (楼主) 3年前
荒街! 3年前
Mr-houzi (楼主) 3年前
PhoenixIcy (作者) 3年前
Mr-houzi (楼主) 3年前
PhoenixIcy (作者) 3年前
Mr-houzi (楼主) 3年前

其实好多 else 可以不写的

3年前 评论
celaraze

因为经常写API,我也把自己常用的接口返回格式的处理过程封装了一下:

{
  "code":200, //沿用了HTTP状态码,自已不用定义,不用铭记
  "message":"get value successfully",
  "data":{
           "ValueString"
         }
}
3年前 评论

请教一个问题蛤。

强制 Json 那里,当我更新一个话题后,故意将传递的id写得贼大,这样数据库就找不到这个用户。用postman模拟这个请求后,他返回的是一个html,404页面。

当我在postman中添加了一个header后 Accept:application/json, 他就返回了json格式的错误。请问这个是上面原因导致的呢?

这里我也是添加了你说的中间件的,依旧会出现上述情况。

我如果用postman请求的时候,如何让所有的响应都是json格式呢?

1年前 评论
sinmu (作者) 1年前

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