error-handling-patterns

错误处理模式

使用稳健的错误处理策略构建具有韧性的应用，优雅地处理失败并提供出色的调试体验。

何时使用此技能

• 在新功能中实现错误处理
• 设计具备错误韧性的 API
• 调试生产环境问题
• 提升应用可靠性
• 为用户和开发者创建更好的错误消息
• 实现重试和断路器模式
• 处理异步/并发错误
• 构建容错的分布式系统

核心概念

1. 错误处理哲学

异常 vs 结果类型：

• 异常：传统的 try-catch，会打断控制流
• 结果类型：显式的成功/失败，函数式方法
• 错误码：C 风格，需要纪律性
• Option/Maybe 类型：用于可空值

各自的适用场景：

• 异常：意外错误、异常状况
• 结果类型：预期错误、验证失败
• Panic/崩溃：不可恢复的错误、编程缺陷

2. 错误类别

可恢复错误：

• 网络超时
• 文件缺失
• 无效的用户输入
• API 速率限制

不可恢复错误：

• 内存不足
• 栈溢出
• 编程缺陷（空指针等）

详细模式与完整示例

详细的模式文档位于 references/details.md。当上述导航层级不够用时，请阅读该文件。

最佳实践

1. 快速失败：尽早验证输入，快速失败
2. 保留上下文：包含堆栈跟踪、元数据、时间戳
3. 有意义的消息：解释发生了什么以及如何修复
4. 合理记录日志：错误 = 记录日志，预期失败 = 不要刷屏日志
5. 在正确的层级处理：在你能够有意义地处理的地方捕获
6. 清理资源：使用 try-finally、上下文管理器、defer
7. 不要吞掉错误：记录日志或重新抛出，不要静默忽略
8. 类型安全的错误：尽可能使用带类型的错误

# Good error handling example
def process_order(order_id: str) -> Order:
    """Process order with comprehensive error handling."""
    try:
        # Validate input
        if not order_id:
            raise ValidationError("Order ID is required")

        # Fetch order
        order = db.get_order(order_id)
        if not order:
            raise NotFoundError("Order", order_id)

        # Process payment
        try:
            payment_result = payment_service.charge(order.total)
        except PaymentServiceError as e:
            # Log and wrap external service error
            logger.error(f"Payment failed for order {order_id}: {e}")
            raise ExternalServiceError(
                f"Payment processing failed",
                service="payment_service",
                details={"order_id": order_id, "amount": order.total}
            ) from e

        # Update order
        order.status = "completed"
        order.payment_id = payment_result.id
        db.save(order)

        return order

    except ApplicationError:
        # Re-raise known application errors
        raise
    except Exception as e:
        # Log unexpected errors
        logger.exception(f"Unexpected error processing order {order_id}")
        raise ApplicationError(
            "Order processing failed",
            code="INTERNAL_ERROR"
        ) from e

常见陷阱

• 捕获范围过宽：except Exception 会隐藏缺陷
• 空的 catch 块：静默吞掉错误
• 记录日志后又重新抛出：产生重复的日志条目
• 未清理资源：忘记关闭文件、连接
• 糟糕的错误消息："发生错误" 毫无帮助
• 返回错误码：使用异常或 Result 类型
• 忽略异步错误：未处理的 promise 拒绝