error-handling-patterns

name	error-handling-patterns
description	错误处理模式 —— 异常分类体系、重试与降级策略、错误码规范与用户友好提示
category	运维
loading	on-demand
triggers	{"keywords":["错误处理","error handling","异常处理","重试","降级","熔断","错误码"]}

错误处理模式

概述

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

使用场景

• 设计全局异常处理机制
• 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、时间戳）？