# 异常处理契约 v1.0

## 1. 异常体系

DomainException（基类）
├── 携带 ErrorCode（枚举）
├── 携带 message（面向用户的描述）
└── 可选携带 cause（原始异常）

所有业务异常必须继承 DomainException 并携带 ErrorCode。
不允许直接抛出 RuntimeException / IllegalStateException 等通用异常表达业务规则。

## 2. ErrorCode 组织方式

按模块前缀分组（锁定）：

    COMMON_VALIDATION_ERROR
    COMMON_INTERNAL_ERROR
    COMMON_OPTIMISTIC_LOCK_CONFLICT
    AUTH_INVALID_CREDENTIALS
    AUTH_TOKEN_EXPIRED
    AUTH_ACCESS_DENIED
    ORDER_NOT_FOUND
    ORDER_ALREADY_CANCELLED
    ORDER_STATUS_INVALID
    ...

命名规则：{MODULE}_{SCENE}，全大写蛇形。
新增模块时在 ErrorCode 枚举中添加对应前缀组。

## 3. ErrorCode → HTTP Status 映射表

| ErrorCode 前缀/具体值 | HTTP Status | 说明 |
|----------------------|-------------|------|
| COMMON_VALIDATION_ERROR | 400 | 参数校验失败 |
| AUTH_INVALID_CREDENTIALS | 401 | 认证失败 |
| AUTH_TOKEN_EXPIRED | 401 | 令牌过期 |
| AUTH_ACCESS_DENIED | 403 | 无权限 |
| *_NOT_FOUND | 404 | 资源不存在 |
| *_ALREADY_* / *_STATUS_INVALID | 409 | 状态冲突 |
| COMMON_OPTIMISTIC_LOCK_CONFLICT | 409 | 乐观锁冲突 |
| COMMON_INTERNAL_ERROR | 500 | 系统内部错误 |

## 4. 统一错误响应格式

{
  "code": 404,                           // HTTP Status（固定，便于前端/网关）
  "errorCode": "ORDER_NOT_FOUND",        // 稳定枚举值（便于埋点/告警/统计）
  "message": "订单不存在",                 // 面向用户，可本地化
  "traceId": "abc-123-def",              // 链路追踪 ID
  "timestamp": "2026-02-11T10:30:00Z",   // 服务器时间
  "details": null                        // 仅 VALIDATION_ERROR 时填充字段级明细
}

各字段职责：
- code：前端快速判断错误大类（4xx / 5xx）
- errorCode：后端精确定位错误场景，用于日志检索 / 告警规则 / 监控大盘
- message：展示给终端用户
- details：VALIDATION_ERROR 时返回 [{"field": "xxx", "message": "xxx"}]
- 生产环境【禁止】在响应中返回堆栈信息

## 5. 异常转换规则

### 规则 1：异常只在 API 层的 GlobalExceptionHandler 转换为 HTTP 响应
- domain/application 层只抛 DomainException
- infrastructure 层将技术异常包装为 DomainException：
  - DataAccessException → COMMON_INTERNAL_ERROR
  - OptimisticLockingFailureException → COMMON_OPTIMISTIC_LOCK_CONFLICT
  - ConnectException / TimeoutException → COMMON_INTERNAL_ERROR

### 规则 2：禁止吞没异常
- 任何 catch 块必须：要么重新抛出，要么记录 WARN/ERROR 日志
- 空 catch 块会被 SpotBugs 检测并阻断 CI

### 规则 3：参数校验 vs 业务校验
- 参数格式校验：Jakarta Validation（@NotNull, @Size, @Pattern 等），
  Controller 层 @Valid/@Validated 拦截，GlobalExceptionHandler 捕获
  MethodArgumentNotValidException → 400 + COMMON_VALIDATION_ERROR + details
- 业务规则校验：Domain 层方法内判断并抛出具体 DomainException

---

## ✅ 可自动检查项

| 规则 | 检查方式 |
|------|---------|
| 所有自定义异常继承 DomainException | ArchUnit: classes in ..exception.. that extend RuntimeException should also extend DomainException |
| 禁止空 catch 块 | SpotBugs: DE_MIGHT_IGNORE + REC_CATCH_EXCEPTION |
| GlobalExceptionHandler 存在且标注 @RestControllerAdvice | ArchUnit: 至少有一个类标注 @RestControllerAdvice 且在 ..api.exception.. 包下 |
| Controller 中 @Valid/@Validated 注解存在 | 人工评审 + Prompt 约束 |

## ❌ 典型违规示例

### 违规 1：直接抛 RuntimeException 表达业务规则

// 错误！
if (order == null) {
    throw new RuntimeException("订单不存在"); // 无 ErrorCode，GlobalExceptionHandler 只能兜底 500
}

// 正确
if (order == null) {
    throw new DomainException(ErrorCode.ORDER_NOT_FOUND);
}

### 违规 2：Infrastructure 层不包装技术异常

// 错误！让 DataAccessException 直接穿透到 API 层
public class OrderPersistenceAdapter implements OrderPersistencePort {
    public Order findById(OrderId id, String customerId) {
        return repo.findByIdAndCustomerId(id.value(), customerId)
            .map(mapper::toDomain)
            .orElse(null); // 返回 null，让上层 NPE → 500
    }
}

// 正确：包装为领域异常
public Order findById(OrderId id, String customerId) {
    return repo.findByIdAndCustomerId(id.value(), customerId)
        .map(mapper::toDomain)
        .orElseThrow(() -> new DomainException(ErrorCode.ORDER_NOT_FOUND));
}