Laravel API如何向客户端发送自定义格式的错误消息？

方法一：统一修改异常处理器（推荐） #

通过修改Laravel默认的异常处理器，让所有API请求的错误都自动返回指定格式，无需在每个业务点重复编写逻辑。

打开app/Exceptions/Handler.php，重写render方法：

<?php

namespace App\Exceptions;

use Illuminate\Validation\ValidationException;
use Throwable;

class Handler extends \Illuminate\Foundation\Exceptions\Handler
{
    public function render($request, Throwable $e)
    {
        // 仅对期望JSON响应的请求（API场景）生效
        if ($request->expectsJson()) {
            // 确定错误状态码，默认返回500
            $statusCode = method_exists($e, 'getStatusCode') ? $e->getStatusCode() : 500;
            // 确定错误消息，优先用异常自带内容，否则用通用提示
            $message = $e->getMessage() ?: '服务器内部错误';

            // 针对表单验证错误（422），提取第一个错误提示（可根据需求调整为返回所有错误）
            if ($e instanceof ValidationException) {
                $message = $e->validator->errors()->first();
                $statusCode = 422;
            }

            // 返回自定义格式的JSON响应
            return response()->json([
                'status' => 'error',
                'message' => $message
            ], $statusCode);
        }

        // 非API请求保持Laravel默认异常处理逻辑
        return parent::render($request, $e);
    }
}

方法二：手动返回自定义响应 #

如果仅在个别业务场景需要自定义错误，可以直接使用response()->json()返回指定格式：

// 示例：检查邮箱格式合法性
$email = $request->input('email');
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
    return response()->json([
        'status' => 'error',
        'message' => 'Invalid email address'
    ], 422);
}

方法三：注册响应宏简化调用 #

在服务提供者中注册响应宏，方便项目内快速调用自定义错误格式：

打开app/Providers/AppServiceProvider.php，在boot方法中添加：

use Illuminate\Support\Facades\Response;

public function boot()
{
    Response::macro('apiError', function ($message, $statusCode = 422) {
        return response()->json([
            'status' => 'error',
            'message' => $message
        ], $statusCode);
    });
}

之后在需要返回错误的地方，直接调用：

return response()->apiError('Invalid email address', 422);

方法四：创建自定义异常类 #

如果需要更灵活的异常管控，可以创建专属的API异常类：

1. 新建app/Exceptions/ApiException.php：

<?php

namespace App\Exceptions;

use Exception;

class ApiException extends Exception
{
    public function render($request)
    {
        // 自动返回自定义格式的JSON响应
        return response()->json([
            'status' => 'error',
            'message' => $this->getMessage()
        ], $this->getCode() ?: 422);
    }
}

2. 在业务代码中抛出该异常：

throw new \App\Exceptions\ApiException('Invalid email address', 422);

内容的提问来源于stack exchange，提问作者HexxonDiv