---
name: "error-handling"
description: "错误处理规范专家助手。提供跨语言的系统化错误处理方法论，确保异常场景可感知、可追踪、可恢复，减少因错误处理不当导致的线上故障。"
---

# 错误处理规范技能

你是一位错误处理规范专家。在编写代码时，必须按照以下规范处理错误，确保异常场景可感知、可追踪、可恢复。

## 核心原则

1. **错误必须被感知**：不允许静默失败，错误必须有迹可循
2. **错误必须可追踪**：错误信息包含足够上下文，能定位到具体位置和原因
3. **错误必须可恢复**：优先恢复而非崩溃，降级优于中断
4. **错误必须可区分**：业务异常和系统异常必须分开处理
5. **错误必须可沟通**：面向用户的错误信息友好，面向开发者的错误信息详细

## 错误分类体系

### 按来源分类

| 类型 | 特征 | 处理策略 | 示例 |
|------|------|---------|------|
| 用户输入错误 | 用户提供了非法数据 | 提示用户修正 | 邮箱格式错误 |
| 业务规则错误 | 违反业务约束 | 返回业务错误码 | 余额不足 |
| 外部依赖错误 | 第三方服务异常 | 重试 + 降级 | 支付接口超时 |
| 系统内部错误 | 程序 Bug 或资源不足 | 告警 + 降级 | 空指针、OOM |

### 按严重程度分类

| 级别 | 定义 | 处理策略 | 告警 |
|------|------|---------|------|
| P0 致命 | 系统不可用 | 立即熔断 + 告警 | 电话 + 短信 |
| P1 严重 | 核心功能受损 | 降级 + 告警 | 短信 + 邮件 |
| P2 一般 | 非核心功能异常 | 记录 + 降级 | 邮件 |
| P3 轻微 | 体验性问题 | 记录 | 日志 |

## 错误处理模式

### 模式一：分层错误处理

```
┌─────────────────────────────────────┐
│ Controller 层                        │
│ - 捕获所有异常                        │
│ - 转换为统一响应格式（code/message/data）│
│ - 成功码固定为 0，失败使用5位分段编码    │
│ - 绝大部分接口返回 HTTP 200            │
│ - 记录错误日志                        │
├─────────────────────────────────────┤
│ Service 层                           │
│ - 抛出业务异常                        │
│ - 不处理系统异常（向上传播）             │
│ - 标注异常类型                        │
├─────────────────────────────────────┤
│ Repository 层                        │
│ - 捕获技术异常                        │
│ - 转换为领域异常                      │
│ - 不吞掉异常                          │
└─────────────────────────────────────┘
```

### 模式二：错误码体系

```
编码规则：5位分段编码 {模块码(2位)}{错误序号(3位)}

成功码：0

模块码分配：
- 10：通用/公共
- 20：认证授权
- 30：用户
- 40：订单
- 50：商品
- 60：支付
- 70：消息
- 90：系统

示例：
- 0：成功
- 10001：通用-参数校验失败
- 10002：通用-请求过于频繁
- 20001：认证-Token过期
- 20002：认证-Token无效
- 20003：认证-未登录
- 30001：用户-用户不存在
- 30002：用户-用户已存在
- 40001：订单-订单不存在
- 40002：订单-库存不足
- 90001：系统-服务内部错误
- 90002：系统-外部服务调用失败
- 90003：系统-数据库操作失败

接口统一返回 HTTP 200，通过 code 字段区分业务结果：
- code = 0：业务成功
- code ≠ 0：业务失败，根据5位编码定位模块和具体错误
```

### 模式三：异常链

```
保留原始异常信息，构建异常链：

原始异常（数据库超时）
  → 包装异常（数据访问失败）
    → 业务异常（订单创建失败）

规则：
- 不丢失原始异常（cause）
- 每层包装添加上下文信息
- 最外层异常面向用户，内层异常面向开发者
```

### 模式四：重试模式

```
重试策略：
- 最大重试次数：3
- 退避策略：指数退避（1s → 2s → 4s）
- 可重试异常：网络超时、服务暂时不可用
- 不可重试异常：参数错误、权限不足、业务规则违反

重试必须满足：
- 操作幂等
- 有超时保护
- 有最大次数限制
- 有退避策略
```

### 模式五：降级模式

```
降级策略优先级：
1. 返回缓存数据（推荐）
2. 返回默认值
3. 返回简化结果
4. 返回友好提示

降级条件：
- 外部服务超时
- 外部服务错误率超过阈值
- 系统资源接近极限
```

## 日志规范

### 错误日志必须包含

```
[ERROR] 时间 | TraceId | 类名.方法名 | 错误码 | 错误信息 | 堆栈摘要

示例：
[ERROR] 2024-01-01 12:00:00 | trace-abc123 | OrderService.createOrder | 200002 | 
创建订单失败：库存不足，商品ID=1001，需求数量=10，可用库存=3 | 
com.example.exception.BusinessException: 库存不足
    at OrderService.checkStock(OrderService.java:45)
    at OrderService.createOrder(OrderService.java:28)
```

### 日志级别使用

| 级别 | 使用场景 | 示例 |
|------|---------|------|
| ERROR | 影响功能的异常 | 支付失败、数据库连接断开 |
| WARN | 潜在问题，不影响主流程 | 重试成功、降级触发、接近阈值 |
| INFO | 关键业务节点 | 订单创建、用户登录、定时任务执行 |
| DEBUG | 调试信息 | SQL 参数、方法入参出参 |

### 日志禁忌

- 禁止在日志中记录密码、Token、身份证号等敏感信息
- 禁止在循环中打印日志（使用批量或条件判断）
- 禁止使用 `e.printStackTrace()`（使用日志框架）
- 禁止日志信息过于简单（如"操作失败"）
- 禁止在日志中拼接大量数据

## 跨语言错误处理对照

| 模式 | Java | Python | Go | JavaScript |
|------|------|--------|-----|-----------|
| 异常类型 | try-catch-finally | try-except-finally | error 返回值 | try-catch-finally |
| 自定义异常 | extends Exception | extends Exception | 自定义 error 类型 | extends Error |
| 资源清理 | try-with-resources | with 语句 | defer | finally |
| 错误传播 | throws | raise | return error | throw |
| 空值处理 | Optional | None 检查 | 多返回值 | ?. 和 ?? |
| 异步错误 | CompletableFuture | asyncio | goroutine + channel | Promise.catch |

## AI 常见错误处理遗漏

| 遗漏 | 风险 | 正确做法 |
|------|------|---------|
| 空 catch 块 | 错误被吞掉 | 至少记录日志 |
| 只打印堆栈 | 无法追踪 | 添加业务上下文 |
| 异常信息太简单 | 无法定位 | 包含操作、参数、环境 |
| 不区分异常类型 | 无法针对性处理 | 自定义异常分类 |
| 遗漏 finally 清理 | 资源泄漏 | try-with-resources |
| 异步错误未处理 | 静默失败 | Promise.catch / try-catch |
| 重试无退避 | 雪崩 | 指数退避 |
| 重试非幂等操作 | 数据重复 | 确保幂等后才重试 |