签入版本

RXThinkCMF_ThinkPhp8_NaiveVue/zh/core/exception.md

@@ -0,0 +1,77 @@
+# 5.16 异常与响应处理
+
+:::tip 概述
+ExceptionHandle 将所有异常统一渲染为 JSON 响应，保证前端始终拿到结构一致的错误信息。
+:::
+
+## 响应结构
+
+```json
+// 成功
+{"code": 0, "ok": true, "msg": "操作成功", "data": {...}}
+
+// 失败
+{"code": 1, "ok": false, "msg": "操作失败", "data": null}
+```
+
+## 异常处理优先级
+
+```php
+// app/ExceptionHandle.php
+
+public function render($request, Throwable $e): Response
+{
+    // 1. 参数验证失败
+    if ($e instanceof ValidateException) {
+        return json(['code' => 1, 'ok' => false, 'msg' => '参数验证失败', 'data' => $e->getError()]);
+    }
+
+    // 2. 数据不存在
+    if ($e instanceof ModelNotFoundException || $e instanceof DataNotFoundException) {
+        return json(['code' => 1, 'ok' => false, 'msg' => '数据不存在']);
+    }
+
+    // 3. JWT 异常（code=401）
+    if ($e instanceof \RuntimeException && in_array($e->getCode(), [401])) {
+        return json(['code' => 1, 'ok' => false, 'msg' => $e->getMessage()]);
+    }
+
+    // 4. HTTP 异常
+    if ($e instanceof HttpException) {
+        return json(['code' => 1, 'ok' => false, 'msg' => $e->getMessage() ?: '请求错误']);
+    }
+
+    // 5. 其他未知异常（生产环境隐藏详情）
+    $msg = config('app.show_error_msg') ? $e->getMessage() : '操作失败';
+    return json(['code' => 1, 'ok' => false, 'msg' => $msg]);
+}
+```
+
+:::danger 生产环境安全
+`SHOW_ERROR_MSG` 必须设为 `false`，否则未知异常的详细信息（可能包含 SQL 语句、文件路径等敏感信息）会暴露给前端。
+:::
+
+## 统一响应类（Result）
+
+```php
+// extend/response/Result.php
+
+Result::success($data, $msg);          // 成功响应
+Result::page($records, $total, ...);   // 分页响应
+Result::fail($msg, $code);             // 失败响应
+Result::unauthorized($msg);            // 401 未授权
+Result::forbidden($msg);               // 403 禁止访问
+Result::notFound($msg);                // 404 数据不存在
+Result::validateError($errors);        // 422 验证错误
+```
+
+## 状态码说明
+
+| code | 含义 | 使用场景 |
+|------|------|----------|
+| 0 | 成功 | 所有成功操作 |
+| 1 | 一般失败 | 业务逻辑失败 |
+| 401 | 未授权 | Token 缺失/无效/过期 |
+| 403 | 禁止访问 | 权限不足 / 租户异常 / 演示环境 |
+| 404 | 数据不存在 | 查询单条记录为空 |
+| 422 | 参数验证失败 | 表单验证不通过 |