dashboard/.qoder/repowiki/knowledge/zh/前后端统一错误响应与拦截机制/前后端统一错误响应与拦截机制.md

kind, name, category, scope, source_files

kind	name	category	scope	source_files
error_handling	前后端统一错误响应与拦截机制	error_handling	**	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 页面。