如何统一Laravel API的响应格式？

嗨，这个问题我之前做Laravel API项目时也碰到过，其实Laravel有不少内置机制能帮你统一所有响应格式——不管是成功响应，还是表单验证错误、4xx/5xx这类系统自动抛出的异常，都能搞定！我给你分享几个实用的方案：

1. 改造全局异常处理器（核心！处理各类异常） #

Laravel所有异常都会经过app/Exceptions/Handler.php处理，我们只需要修改里面的render方法，就能把API请求的所有异常转换成你要的格式：

public function render($request, Throwable $e)
{
    // 判断是否为API请求（可根据路由前缀、请求头或Accept类型调整）
    if ($request->wantsJson() || $request->is('api/*')) {
        // 处理表单验证异常
        if ($e instanceof ValidationException) {
            return response()->json([
                'success' => false,
                'message' => '表单验证失败',
                'errors' => $e->errors()
            ], $e->status);
        }

        // 处理HTTP异常（比如404、401、500等）
        if ($e instanceof HttpException) {
            return response()->json([
                'success' => false,
                'message' => $e->getMessage() ?: '请求出错',
                'errors' => []
            ], $e->getStatusCode());
        }

        // 处理其他所有异常（生产环境建议隐藏具体错误信息）
        return response()->json([
            'success' => false,
            'message' => app()->environment('production') ? '服务器内部错误' : $e->getMessage(),
            'errors' => []
        ], 500);
    }

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

这样不管是404资源不存在、422验证失败，还是500服务器报错，都会输出你定义的统一错误格式。

2. 定义成功响应宏（简化成功响应代码） #

为了让成功响应也更统一，你可以在App\Providers\AppServiceProvider.php的boot方法里定义一个响应宏，以后直接调用就行：

use Illuminate\Support\Facades\Response;

public function boot()
{
    Response::macro('success', function ($data = []) {
        return response()->json([
            'success' => true,
            'data' => $data
        ]);
    });
}

之后在控制器里返回成功响应时，不用每次手动写数组，直接用：

return response()->success(['user' => $user]);

既简洁又能保证格式完全统一。

3. 自定义表单验证请求（细化验证错误） #

如果你用Laravel的Form Request做表单验证，可以在自定义请求类里重写failedValidation方法，让验证失败时直接返回我们想要的格式：

use Illuminate\Contracts\Validation\Validator;
use Illuminate\Validation\ValidationException;

class StoreUserRequest extends FormRequest
{
    // ... 这里放你的验证规则和授权逻辑

    protected function failedValidation(Validator $validator)
    {
        throw new ValidationException($validator, response()->json([
            'success' => false,
            'message' => '表单验证失败',
            'errors' => $validator->errors()
        ], 422));
    }
}

这个方法和全局异常处理器的效果类似，但可以针对特定的验证请求做个性化调整（比如修改错误提示语）。

按照这几个步骤配置完后，你的API不管是成功返回数据，还是遇到各种错误、异常，都会输出你想要的统一格式啦！

备注：内容来源于stack exchange，提问作者user29997155