findscripter 何时使用
- 为新功能、API 或分布式系统设计错误处理策略时使用。
- 排查线上故障、提升可靠性、改进面向用户/开发者的错误信息时使用。
- 实现重试、熔断、限流、并发/异步错误处理或故障容错时使用。
- 触发词：错误处理、异常设计、重试、熔断、优雅降级、Result 类型、故障容错。
不该用的边界：
- 纯查日志、聚合指标、性能压测：本技能给处理模式，不替代可观测性工具与压测。
- 实现具体业务逻辑本身（"这功能怎么写"）：先写功能，错误处理是其中一环而非全部。
- 依赖/CVE/许可证体检 → 用
dependency-auditor；找改动里的 bug → 用code-reviewer。 - 不替代环境特定的验证、测试与专家评审；缺关键输入/约束/成功标准时先问清再做。
步骤 / 指令
1. 先分类错误，再选机制
- 可恢复（网络超时、文件缺失、非法输入、限流）→ 重试/降级/校验。
- 不可恢复（OOM、栈溢出、空指针等编程 bug）→ 快速失败/崩溃，不要 catch 后吞掉。
2. 选错误表达方式（按场景而非一刀切）
- 异常 Exception：意外、异常条件。
- Result/Either 类型：预期内的失败、校验错误（显式 ok/err，强制处理）。
- Option/Maybe：可空值。
- Panic/Crash：不可恢复的编程错误。
3. 建立类型化错误层级
- 定义 ApplicationError 基类，挂 code / details / timestamp。
- 派生 ValidationError、NotFoundError、ExternalServiceError 等语义子类。
- 外部服务错误要带 service 等上下文；抛出时用 `raise ... from e` / `%w` 保留因果链。
4. 在正确层级处理
- 在能"有意义地处理"的层捕获；否则向上传播。
- 已知应用错误直接 re-raise；未知错误记一次日志再包装抛出，避免重复日志。
5. 加韧性模式（按需）
- 重试 + 指数退避：仅对可重试异常重试，限定 max_attempts，退避 backoff_factor ** attempt。
- 熔断 Circuit Breaker：CLOSED/OPEN/HALF_OPEN 三态，失败超阈值断开，超时后半开试探。
- 优雅降级：主路径失败回退到缓存/备用源/默认值。
- 错误聚合：校验多字段时收集全部错误再一次性抛 AggregateError，而非首错即停。
6. 清理资源
- try-finally / context manager / defer，确保文件、连接、事务回滚或关闭。
规则（核心约束，务必遵守）：
- 快速失败：尽早校验输入。
- 保留上下文：栈、元数据、时间戳一并带上。
- 消息要可操作：说清发生了什么、怎么修，禁止 "Error occurred" 式无效信息。
- 日志要克制：真错误记日志；预期内失败别刷屏。
- 不要吞错误：要么记日志要么重抛，禁止空 catch 静默吞掉。
- 不要又记日志又重抛同一处：会产生重复日志。
- 尽量用类型化错误，少用裸错误码。
示例
自定义异常层级（Python）：
class ApplicationError(Exception):
def __init__(self, message: str, code: str = None, details: dict = None):
super().__init__(message)
self.code = code
self.details = details or {}
self.timestamp = datetime.utcnow()
class ValidationError(ApplicationError): pass
class NotFoundError(ApplicationError): pass
class ExternalServiceError(ApplicationError):
def __init__(self, message: str, service: str, **kwargs):
super().__init__(message, **kwargs)
self.service = service
重试 + 指数退避（Python，只对指定异常重试）：
def retry(max_attempts=3, backoff_factor=2.0, exceptions=(Exception,)):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
last = None
for attempt in range(max_attempts):
try:
return func(*args, **kwargs)
except exceptions as e:
last = e
if attempt < max_attempts - 1:
time.sleep(backoff_factor ** attempt)
continue
raise
raise last
return wrapper
return decorator
Result 类型（TypeScript，显式成功/失败）：
type Result<T, E = Error> =
| { ok: true; value: T }
| { ok: false; error: E };
function parseJSON<T>(json: string): Result<T, SyntaxError> {
try { return { ok: true, value: JSON.parse(json) as T }; }
catch (e) { return { ok: false, error: e as SyntaxError }; }
}
const r = parseJSON<User>(userJson);
if (r.ok) console.log(r.value.name);
else console.error('Parse failed:', r.error.message);
错误包装与解包（Go，保留因果链）：
func processUser(id string) error {
user, err := getUser(id)
if err != nil {
return fmt.Errorf("process user failed: %w", err) // %w 包装
}
_ = user
return nil
}
// errors.Is 比对哨兵错误，errors.As 提取具体类型
熔断器三态（Python，要点）：
class CircuitState(Enum):
CLOSED = "closed" # 正常
OPEN = "open" # 失败，拒绝请求
HALF_OPEN = "half_open" # 试探是否恢复
# 失败计数 >= failure_threshold → OPEN；
# OPEN 且距上次失败 > timeout → 转 HALF_OPEN；
# HALF_OPEN 连续成功 >= success_threshold → CLOSED。
优雅降级（Python，主失败回退）：
def with_fallback(primary, fallback, log_error=True):
try:
return primary()
except Exception as e:
if log_error:
logger.error(f"Primary function failed: {e}")
return fallback()
# get_user_profile = with_fallback(缓存, 数据库)
注意事项
常见坑（务必规避）：
- 捕获过宽：裸
except Exception会掩盖 bug，按需精确捕获。 - 空 catch 块：静默吞错误，最难排查。
- 又记又抛：同一错误在多层重复记日志。
- 忘记清理：文件、连接、事务未关闭/回滚。
- 错误信息空洞："发生错误"对排障毫无帮助。
- 滥用错误码：优先异常或 Result 类型。
- 忽略异步错误：未处理的 promise rejection。
其他：
- "处理在正确层级"：能有意义处理就捕获，否则传播；别在底层硬吞。
- 区分可恢复与不可恢复：编程 bug 应快速失败暴露，而非重试或降级掩盖。
- 重试只对幂等且可重试的操作；对非幂等写操作加重试前先确认安全。
- 输出方案不替代环境特定的测试与验证。
互见
- requires：无。
- related：
code-reviewer（审查改动中的错误处理/资源释放/异常吞掉等正确性问题）、dependency-auditor（依赖与供应链层面的风险）。 - combines_with：无。
本条目为适配重写，采编自 sickn33/antigravity-awesome-skills（MIT 许可证）的 error-handling-patterns。