error-handling-patterns

Files (2)

• SKILL.md
• SKILL.md.disabled

SKILL.md (first lines)

# 错误处理模式

## 概述
提供覆盖应用全链路的错误处理策略，包含错误分类、重试与退避、降级兜底、熔断保护和用户提示规范。

## 使用场景
- 设计全局异常处理机制
- API 调用频繁超时需要引入重试和熔断
- 用户反馈错误提示不友好或暴露内部信息
- 分布式事务中需要补偿和回滚策略

## 核心原则
1. **错误分类先行**：区分可恢复错误（重试解决）、不可恢复错误（返回失败）、业务错误（提示用户）。
2. **重试必须带退避**：固定间隔重试会导致雪崩。指数退避 + 随机抖动是标准做法。
3. **熔断保护系统**：连续失败达到阈值后快速失败（fail-fast），避免级联故障扩散。
4. **用户提示安全第一**：对外错误消息不暴露堆栈、路径、SQL、密钥。内部日志可记录完整上下文。
5. **错误不丢失**：每个错误要么处理，要么向上传播，绝不静默 `pass` 或空 `catch`。

## 实践要点
- **错误码规范**：全局统一错误码表，格式如 `MODULE_ERROR_CODE`（`USER_001`, `ORDER_023`）
- **重试策略**：网络类错误最多 3 次重试，退避 1s/2s/4s + 随机 0-500ms 抖动
- **熔断器三态**：关闭（正常）→ 打开（快速拒绝）→ 半开（探测恢复）
- **幂等设计**：重试操作必须幂等，通过幂等键防止重复处理

## 检查清单
- [ ] 是否有全局异常拦截层统一处理未被捕获的错误？
- [ ] 对外错误消息是否确认无敏感信息泄露？
- [ ] 外部调用是否有合理的超时、重试和熔断机制？
- [ ] 分布式操作是否有补偿/回滚策略？
- [ ] 错误日志是否包含足够的排查上下文（请求 ID、用户 ID、时间戳）？

From Sweetteabittersugar/agency, MIT.

More from Sweetteabittersugar/agency