---
kind: error_handling
name: 前后端统一错误响应与拦截机制
category: error_handling
scope:
    - '**'
source_files:
    - backend/src/utils/response.js
    - backend/src/middleware/auth.js
    - backend/src/app.js
    - frontend/src/utils/request.js
---

本仓库采用「后端统一响应体 + 前端 Axios 拦截器」的轻量级错误处理方案，未引入专门的错误类型库或全局异常中间件。

**后端（Express）**
- 统一响应封装：`backend/src/utils/response.js` 提供 `ApiResponse.success / error / noData` 三个工厂方法，约定 `code=1` 成功、`code=0` 业务错误、`code=2` 无数据；`PageData` 用于分页结构。
- 路由层自行 try/catch：各 `routes/*.js` 在控制器内捕获异常，记录 `logger.error(e.message)` 后返回 `ApiResponse.error(...)`，错误消息多为硬编码中文提示，未使用 HTTP 状态码区分语义。
- 认证中间件 `middleware/auth.js` 单独处理鉴权错误：401 返回 `{ detail: '...' }`，403 返回权限不足信息，与业务错误体结构不同。
- 服务层 `services/*.js` 直接 `throw new Error(...)` 向上抛出具体错误（如 Redis/S3/曲线接口失败），由调用方路由捕获。
- 应用入口 `app.js` 仅在启动阶段同步数据库时 try/catch，未注册全局 Express 错误处理中间件（`app.use((err, req, res, next) => ...)`）。

**前端（Vue3 + Axios）**
- `frontend/src/utils/request.js` 通过 Axios 拦截器集中处理：
  - 请求拦截：自动注入 `Authorization: Bearer <token>`，跳过 `/auth/login`。
  - 响应拦截：当 `res.code === 0` 时，若 `config.skipErrorToast` 未设置则弹出 `ElMessage.error`，并将 `responseData` 挂载到抛出的 Error 对象上供上层消费。
  - HTTP 错误：401 清除本地 token、跳转登录页并携带 redirect；403 显示警告；其他网络错误统一 `ElMessage.error`。
- 业务 API 模块（`frontend/src/api/*.js`）基于此 request 实例发起请求，依赖 Promise reject 分支处理业务错误。

**设计决策与不足**
- 优点：前后端对 `code/msg/data` 协议一致，前端拦截器屏蔽了重复的错误提示逻辑。
- 不足：缺少统一的错误码枚举、HTTP 状态码未与业务错误解耦、未定义全局错误中间件导致未捕获异常可能返回默认 HTML 500 页面。