Laravel自定义异常返回JSON详解

本文深入解析了 Laravel 中 API 异常无法自动返回统一 JSON 格式的根本原因——默认异常处理器对 API 请求缺乏针对性处理，导致 ValidationException、ModelNotFoundException 等关键异常仍返回 HTML 页面或空白响应；强调必须在 `Handler::render()` 中主动拦截并精准识别 API 请求（优先使用 `$request->expectsJson()` 而非 URL 前缀），为各类异常定制符合 REST 规范的 JSON 响应：严格区分 HTTP 状态码（如 422/404/201/204）与业务错误码（如 `code: 1002`），杜绝中间件兜底或控制器手动封装的误区，并提醒开发环境下需绕过 Ignition 调试页以确保 JSON 一致性——掌握这些细节，才能真正实现前后端契约清晰、错误可读、调试可控的高质量 API 异常体验。

API请求抛出异常时，为什么返回的不是你定义的 JSON 格式？

因为默认的 render() 方法对 API 请求不做特殊处理，ValidationException、ModelNotFoundException 等直接走 Laravel 内置逻辑：前者可能返回 HTML 表单错误页，后者返回空白 404 响应体，根本不会套上 code/message/data 结构。

必须在 App\Exceptions\Handler::render() 中显式拦截并构造 JSON 响应，否则前端永远收不到统一格式。

• 别指望中间件兜底——异常可能发生在路由匹配前或视图渲染时，中间件根本没机会执行
• 别在控制器里手动封装——500 错误、模型未找到等压根不会进控制器
• 开发环境开启 APP_DEBUG=true 时，Laravel 默认返回 Ignition 调试页，要强制 JSON 得加判断条件

怎么用 $request->expectsJson() 准确识别 API 请求？

$request->expectsJson() 比 $request->is('api/*') 更可靠，它检查请求头是否含 Accept: application/json 或 X-Requested-With: XMLHttpRequest，Axios、Fetch、Postman 默认都带，浏览器地址栏直访问则不匹配。

实操建议组合使用，兼顾兼容性：

• if ($request->expectsJson() || $request->is('api/*')) { ... } —— 覆盖绝大多数场景
• 不要只依赖 URL 前缀，子域名（如 v1.api.example.com）或无前缀的 GraphQL 接口会漏判
• 测试时用 curl -H "Accept: application/json" http://localhost:8000/user，避免被重定向或返回 Blade 页面

常见异常类型必须单独处理，不能全交给 parent::render()

直接 return parent::render($request, $exception) 对 API 是灾难性的：调试模式下暴露完整堆栈，生产环境返回空白 500 页面，完全脱离你的统一结构。

关键异常必须提前拦截并返回标准 JSON：

• ValidationException：用 $exception->errors() 提取字段级错误，状态码固定 422，别用 $exception->getMessage()
• ModelNotFoundException：返回 response()->json(['code' => 404, 'message' => '资源不存在'], 404)，别留英文默认消息
• 业务自定义异常（如 InsufficientBalanceException）：靠 $exception->getCode() 取业务码，$exception->getMessage() 取提示语
• Throwable（兜底）：生产环境只返回 ['code' => 500, 'message' => 'Server Error']，禁止带堆栈或文件路径

response()->json() 的第三个参数不是可选项，是 REST 合规关键

很多人写 response()->json(['data' => $user])，结果创建资源后仍是 200 状态码，违反 REST 规范。HTTP 状态码必须明确传递，且和业务语义匹配。

不同场景对应不同状态码：

• 创建成功：response()->json(['data' => $user], 201)
• 删除成功：response()->json(['message' => 'OK'], 204)（注意：204 不允许带响应体，别传数组）
• 验证失败：response()->json(['code' => 422, 'message' => '参数校验失败', 'errors' => $exception->errors()], 422)
• 认证失败：response()->json(['message' => 'Unauthenticated.'], 401)

业务错误码（如 1002）和 HTTP 状态码（如 400）是两回事，别混用；前者进 JSON body 的 code 字段，后者是响应头里的真实状态码。

到这里，我们也就讲完了《Laravel自定义异常返回JSON详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！