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/service/request/index.ts frontend/src/service/request/shared.ts

后端（Node.js + Express）

• 统一响应体：backend/src/utils/response.js 导出 ApiResponse，提供 success(data, msg)、error(msg, code=0)、noData(msg) 三个工厂方法，所有业务路由通过 res.json(ApiResponse.xxx(...)) 返回 { code, msg, data } 结构。
• 认证错误：backend/src/middleware/auth.js 的 authMiddleware 对未登录/无效/过期 JWT 直接以 HTTP 401 + { detail: '...' } 形式返回；requireSuperAdmin 对权限不足返回 403。这些 401/403 走的是 HTTP 状态码路径，不走 ApiResponse。
• 异常捕获：各路由文件内大量使用 try/catch 包裹异步逻辑，失败时调用 ApiResponse.error(...)；入口 app.js 仅在启动阶段同步数据库时 catch 并记录日志，未注册全局 express error handler，因此未捕获的异常会以 Node 默认方式抛出。
• 无全局错误中间件：未发现类似 app.use((err, req, res, next) => ...) 的全局错误处理中间件，错误传播依赖每个路由自行 try/catch 后返回 ApiResponse。

前端（Vue3 + Axios）

• 请求封装：frontend/src/service/request/index.ts 基于 @sa/axios 的 createFlatRequest 创建 request 实例，集中处理成功/失败分支。
• 成功判定：isDashboardSuccessCode 将后端 code === '1' 或 '2' 视为成功（2 表示“无数据但仍 OK”），其余进入 onBackendFail。
• 后端失败处理：
  • 根据环境变量 VITE_SERVICE_LOGOUT_CODES / VITE_SERVICE_MODAL_LOGOUT_CODES / VITE_SERVICE_EXPIRED_TOKEN_CODES 分别执行静默登出、弹窗确认登出、刷新 token 并重试。
  • 通过 showErrorMsg（定义于 shared.ts）统一弹出错误提示，支持 skipErrorToast 配置由调用方抑制 toast。
• HTTP 错误处理：onError 中针对 401 自动清理 auth store 并显示 detail；403 显示“无权限执行此操作”；其他错误优先取 response.data.msg，否则回退到 axios message。
• demo 请求：demoRequest 使用独立的 success/fail 策略，不干扰主请求的错误流。

约定与规则

层面	约定
后端成功	ApiResponse.success(data, msg) → { code: 1, msg, data }
后端业务错误	ApiResponse.error(msg, code) → { code, msg, data: null }，code 为数字字符串（如 0）
后端空数据	ApiResponse.noData(msg) → { code: 2, msg, data: null }，前端视作成功
认证失败	401 + { detail: '...' }（JWT 相关）
权限不足	403 + { detail: '...' }
前端成功判定	`code === '1'
前端错误展示	统一经 showErrorMsg，可通过 config.skipErrorToast = true 抑制
全局错误中间件	后端未实现，需在各路由 try/catch 后返回 ApiResponse

关键文件

• backend/src/utils/response.js — 统一响应体工厂
• backend/src/middleware/auth.js — 认证/鉴权错误（401/403）
• backend/src/app.js — 应用入口（仅启动期 try/catch）
• frontend/src/service/request/index.ts — Axios 拦截器与错误分发
• frontend/src/service/request/shared.ts — showErrorMsg 等共享工具