异常处理规范

---
description: 后端处理异常时参考规则
alwaysApply: false
enabled: true
updatedAt: 2026-09-11T02:37:48.394Z
provider: 
---

# 异常处理规范

## 1. 基本原则
- 业务异常统一使用 `BizException`。
- **抛异常默认使用 `BizException`**：除系统/框架级异常（如 `@Transactional`
  依赖回滚的受检异常、断言工具内置异常）外，业务分支、状态流转守卫、资源冲突、参数校验等一切可预期失败均默认抛出
  `BizException`。
- **禁止使用 `IllegalStateException`、`IllegalArgumentException` 等作为业务规则校验的载体**：聚合根状态流转守卫、领域规则校验等业务场景应统一抛
  `BizException`（可携带错误信息，如 `new BizException("只有开票中状态才能变更为开票成功")`），禁止散落 JDK
  内置异常表达业务失败，否则无法被全局异常处理器统一映射为业务错误响应。
- 禁止直接抛出裸 `RuntimeException` 作为业务分支。
- 不吞异常：必须记录上下文并保留根因。
- 不暴露敏感细节：对外错误信息避免泄漏内部实现。

## 2. 异常分类
- **参数异常**：请求参数缺失、格式非法、边界越界。
- **权限异常**：未登录、Token 失效、越权访问。
- **业务异常**：余额不足、状态不允许、资源冲突。
- **系统异常**：网络超时、数据库故障、第三方不可用。

## 3. 错误码规范
- 错误码应稳定、可检索、可统计。
- 按业务域分段编码，避免全局冲突。
- 新增错误码必须补充含义、触发条件与处理建议。

## 4. 日志规范
- 日志必须记录：`traceId`、`userId`、`api`、`errorCode`、`bizKey`。
- 业务异常记录 `warn`，系统不可恢复异常记录 `error`。
- 日志信息要说明“在哪个业务步骤失败”。

## 5. 全局异常处理
- 统一异常处理器负责异常到标准响应的映射。
- Controller 不自行拼装异常返回体。
- 未知异常映射为通用系统错误码，并保留完整日志。

## 6. 禁止行为
- 使用异常做正常流程分支。
- 捕获后直接 `return null` 或空对象。
- 把技术异常原文直接返回给前端。
- 在聚合根、领域服务、应用服务、Controller 中用 `IllegalStateException`、`IllegalArgumentException` 等 JDK
  内置异常表达业务规则失败；业务校验失败统一抛 `BizException`。

## 7. 评审检查点
- 是否使用了统一异常体系？
- 业务规则失败、状态守卫、参数校验是否默认抛 `BizException`，而非 `IllegalStateException`/`IllegalArgumentException` 等 JDK
  内置异常？
- 异常信息是否足以定位问题？
- 是否区分了业务可预期失败与系统不可预期失败？
- 是否存在吞异常或重复包装导致信息丢失？