# 错误处理标准

[目的：统一错误的分类、形状、传播、日志记录和监控方式]

## 理念
- 尽可能快速失败；在系统边界优雅降级
- 跨堆栈一致的错误形状（人类和机器可读）
- 在接近源处处理已知错误；将未知错误暴露给全局处理器

## 分类（按来源决定处理）
- 客户端: 输入/验证/用户操作问题 → 4xx
- 服务器: 系统故障/意外异常 → 5xx
- 业务: 规则/状态违规 → 4xx（例如，409）
- 外部: 第三方/网络故障 → 映射到5xx或带上下文的4xx

## 错误形状（单一规范格式）
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "requestId": "trace-id",
    "timestamp": "ISO-8601"
  }
}
```
原则: 稳定的代码枚举，无秘密，包含跟踪信息。

## 传播（在哪里转换）
- API层: 将领域错误转换为HTTP状态 + 规范主体
- 服务层: 抛出类型化业务错误，避免字符串类型错误
- 数据/外部层: 用安全、可操作的代码包装提供者错误
- 未知错误: 冒泡到全局处理器 → 500 + 通用消息

示例模式:
```typescript
try { return await useCase(); }
catch (e) {
  if (e instanceof BusinessError) return respondMapped(e);
  logError(e); return respondInternal();
}
```

## 日志记录（上下文而非噪音）
记录: 操作、userId（如可用）、代码、消息、堆栈、requestId、最小上下文。
不记录: 密码、令牌、秘密、完整PII、包含敏感数据的完整主体。
级别: ERROR（故障）、WARN（可恢复/边缘）、INFO（关键事件）、DEBUG（诊断）。

## 重试（仅在安全时）
重试当: 网络/超时/瞬态5xx且操作是幂等的。
不重试: 4xx、业务错误、非幂等流程。
策略: 指数退避 + 抖动，限制尝试；需要幂等性密钥。

## 监控和健康
跟踪: 按代码/类别的错误率、延迟、饱和度；在峰值/SLI违规时告警。
暴露健康: `/health`（存活）、`/health/ready`（就绪）。将错误链接到跟踪。

---
_关注模式和决策。无实施细节或详尽列表。_
