---
name: error-handling
when: '异常处理, 错误处理, 全局异常, 错误码, Exception, BusinessException, 状态码, 报错, 异常捕获, 错误响应'
scope:
  - backend
products:
  - '*'
id: ka-pattern-error-handling
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 异常处理
  - 错误处理
  - 全局异常
  - 错误码
  - Exception
  - BusinessException
  - 状态码
  - 报错
  - 异常捕获
  - 错误响应
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 必须使用 @ControllerAdvice 全局异常处理器，禁止散落的 try-catch 吞异常
- 业务异常必须使用自定义 BusinessException 携带错误码和消息
- 禁止将异常堆栈信息返回给前端
- 系统异常必须记录 ERROR 日志并返回通用提示，不暴露内部细节
- 参数校验失败必须返回 HTTP 400
- 每个用户可见写操作必须定义失败反馈：提示文案、重试建议、是否可恢复
- 权限失败、校验失败、资源不存在、冲突失败、系统异常必须有区别化处理
- 前端提示与接口错误码必须可回链，不得一个写"无权限"、一个写"操作失败"
- 若失败后需要用户补动作（刷新、重新登录、补齐字段、稍后重试），必须写明
- 全局异常处理器必须区分业务异常（可预期）和系统异常（不可预期），分别返回不同错误码
- 错误响应必须包含 traceId，便于日志追踪关联
- 前端必须对每个 API 调用做错误处理（toast/notification），禁止静默失败

## 验收项
- [AC-01] 所有异常经全局处理器返回
- [AC-02] 业务异常返回具体错误码和消息
- [AC-03] 系统异常不暴露堆栈给前端
- [AC-04] 校验失败返回 400 + 字段错误详情
- [AC-05] 用户可见写操作有失败反馈（提示+重试建议）
- [AC-06] 前端提示与后端错误码可回链
- [AC-07] 业务异常与系统异常分别处理
- [AC-08] 错误响应包含 traceId
- [AC-09] 前端 API 调用有错误提示
