Error Handling

错误处理规范技能

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

核心原则

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

错误分类体系

按来源分类

按严重程度分类

错误处理模式

模式一：分层错误处理

┌─────────────────────────────────────┐
│ 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)

日志级别使用

日志禁忌

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

跨语言错误处理对照

AI 常见错误处理遗漏