ui 优化

2026-07-14 18:56:13 +08:00
parent 4f10cc1648
commit 003b44e2bd
32 changed files with 1082 additions and 375 deletions
@@ -0,0 +1,38 @@
+---
+kind: error_handling
+name: 前后端错误处理体系：统一响应体 + 拦截器 + 中间件
+category: error_handling
+scope:
+    - '**'
+source_files:
+    - backend/src/utils/response.js
+    - backend/src/middleware/auth.js
+    - backend/src/routes/auth.js
+    - backend/src/app.js
+    - frontend/src/utils/request.js
+---
+
+本仓库在后端（Express）与前端（Vue3 + Axios）分别建立了结构化的错误处理机制，核心思路是“后端返回统一 JSON 结构，前端通过拦截器集中处理 HTTP 状态码与业务码”。
+
+## 后端（Express）
+- **统一响应体**：`backend/src/utils/response.js` 导出 `ApiResponse.success / error / noData`，所有路由以 `{ code, msg, data }` 形式返回。业务错误使用 `code: 0`，成功使用 `code: 1`，无数据使用 `code: 2`。
+- **认证中间件**：`backend/src/middleware/auth.js` 的 `authMiddleware` 校验 Bearer Token，失败直接返回 `401 { detail }`；`requireSuperAdmin` 对非超级管理员返回 `403 { detail }`。这些 4xx 响应走 HTTP 状态码通道，不走业务码通道。
+- **路由层 try/catch**：各路由文件（如 `routes/auth.js`、`routes/blacklist.js`）在每个接口内包裹 try/catch，捕获异常后记录 `logger.error` 并以 `ApiResponse.error('xxx')` 返回，避免未捕获异常导致进程崩溃。
+- **全局异常**：未发现 Express 级别的 `app.use((err, req, res, next) => ...)` 全局错误处理器，异常由路由自身 catch 兜底。
+- **外部依赖错误**：Redis 连接在 `config/redis.js` 中监听 `'error'` 事件并仅记录日志，不中断服务。
+
+## 前端（Axios 拦截器）
+- **请求拦截器**：`frontend/src/utils/request.js` 自动注入 `Authorization: Bearer <token>`，跳过 `/auth/login`。
+- **响应拦截器**：
+  - 当后端返回 `res.code === 0` 时，视为业务错误，构造 `Error(res.msg)` 并通过 `ElMessage.error` 提示；若调用方设置 `skipErrorToast` 则静默拒绝。
+  - HTTP 401：清除本地 token，解析 `response.data.detail` 提示，并跳转到 `/login?redirect=...`。
+  - HTTP 403：弹出 `detail` 警告。
+  - 其他网络错误：打印 `console.error` 并用 `ElMessage.error` 提示“网络错误”。
+- **组件级 catch**：视图中的异步操作（如 `useModelList.js`）在 catch 中再次用 `ElMessage.error` 做兜底提示，形成“拦截器通用提示 + 业务特定提示”的双层策略。
+
+## 约定与规则
+1. 后端所有业务错误必须通过 `ApiResponse.error(msg, code?)` 返回，不要直接 `throw` 裸 Error。
+2. 认证相关错误优先使用 HTTP 401/403 + `{ detail }` 结构，以便前端拦截器区分处理。
+3. 路由函数内部应包裹 try/catch，确保异常被记录并转为 `ApiResponse.error`。
+4. 前端如需自定义错误提示（如推送进度弹窗），在 axios 配置中传入 `skipErrorToast: true` 以抑制默认 ElMessage。
+5. 未实现全局错误中间件，新增路由需自行遵循 try/catch 模式。