python-error-handling

来源声明：本技能内容源自 wshobson/agents （MIT License, Copyright (c) 2024 Seth Hobson；完整许可文本见同目录 LICENSE.txt）。 使用、修改与再分发须遵守该 MIT 许可条款并保留版权声明。

中文描述

本技能提供全栈开发相关的最佳实践和模式指导。

---

name: python-error-handling description: Python 错误处理模式，包括输入验证、异常层次结构和部分失败处理。适用于实现验证逻辑、设计异常策略、处理批处理失败或构建健壮的 API。

Python 错误处理

通过恰当的输入验证、有意义的异常和优雅的失败处理，构建健壮的 Python 应用。良好的错误处理有助于调试，并能提高系统可靠性。

何时使用此技能

• 验证用户输入和 API 参数
• 为应用设计异常层次结构
• 处理批量操作中的部分失败
• 将外部数据转换为领域类型
• 构建用户友好的错误消息
• 实现快速失败验证模式

核心概念

1. 快速失败

在执行开销较大的操作之前尽早验证输入。尽可能一次性报告所有验证错误。

2. 有意义的异常

使用恰当的异常类型并提供上下文。消息应说明出了什么问题、原因是什么，以及如何修复。

3. 部分失败

在批量操作中，不要让一次失败导致所有操作中止。分别跟踪成功和失败的项目。

4. 保留上下文

链接异常，以保留完整的错误链，便于调试。

快速入门

def fetch_page(url: str, page_size: int) -> Page:
    if not url:
        raise ValueError("'url' is required")
    if not 1 <= page_size <= 100:
        raise ValueError(f"'page_size' must be 1-100, got {page_size}")
    # Now safe to proceed...

基本模式

模式 1：尽早验证输入

在 API 边界处、任何处理开始之前验证所有输入。

def process_order(
    order_id: str,
    quantity: int,
    discount_percent: float,
) -> OrderResult:
    """Process an order with validation."""
    # Validate required fields
    if not order_id:
        raise ValueError("'order_id' is required")

    # Validate ranges
    if quantity <= 0:
        raise ValueError(f"'quantity' must be positive, got {quantity}")

    if not 0 <= discount_percent <= 100:
        raise ValueError(
            f"'discount_percent' must be 0-100, got {discount_percent}"
        )

    # Validation passed, proceed with processing
    return _process_validated_order(order_id, quantity, discount_percent)

模式 2：尽早转换为领域类型

在系统边界处将字符串和外部数据解析为类型化的领域对象。

from enum import Enum

class OutputFormat(Enum):
    JSON = "json"
    CSV = "csv"
    PARQUET = "parquet"

def parse_output_format(value: str) -> OutputFormat:
    """Parse string to OutputFormat enum.

    Args:
        value: Format string from user input.

    Returns:
        Validated OutputFormat enum member.

    Raises:
        ValueError: If format is not recognized.
    """
    try:
        return OutputFormat(value.lower())
    except ValueError:
        valid_formats = [f.value for f in OutputFormat]
        raise ValueError(
            f"Invalid format '{value}'. "
            f"Valid options: {', '.join(valid_formats)}"
        )

# Usage at API boundary
def export_data(data: list[dict], format_str: str) -> bytes:
    output_format = parse_output_format(format_str)  # Fail fast
    # Rest of function uses typed OutputFormat
    ...

模式 3：使用 Pydantic 进行复杂验证

使用 Pydantic 模型进行结构化输入验证，并自动生成错误消息。

from pydantic import BaseModel, Field, field_validator

class CreateUserInput(BaseModel):
    """Input model for user creation."""

    email: str = Field(..., min_length=5, max_length=255)
    name: str = Field(..., min_length=1, max_length=100)
    age: int = Field(ge=0, le=150)

    @field_validator("email")
    @classmethod
    def validate_email_format(cls, v: str) -> str:
        if "@" not in v or "." not in v.split("@")[-1]:
            raise ValueError("Invalid email format")
        return v.lower()

    @field_validator("name")
    @classmethod
    def normalize_name(cls, v: str) -> str:
        return v.strip().title()

# Usage
try:
    user_input = CreateUserInput(
        email="[email protected]",
        name="john doe",
        age=25,
    )
except ValidationError as e:
    # Pydantic provides detailed error information
    print(e.errors())

模式 4：将错误映射为标准异常

恰当地使用 Python 内置异常类型，并根据需要补充上下文。

失败类型	异常	示例
输入无效	ValueError	参数值错误
类型错误	TypeError	期望字符串，实际得到 int
项目缺失	KeyError	未找到字典键
操作失败	RuntimeError	服务不可用
超时	TimeoutError	操作耗时过长
文件未找到	FileNotFoundError	路径不存在
权限被拒绝	PermissionError	禁止访问

# Good: Specific exception with context
raise ValueError(f"'page_size' must be 1-100, got {page_size}")

# Avoid: Generic exception, no context
raise Exception("Invalid parameter")

详细示例和模式

详细章节（从 ## Advanced Patterns 开始）位于 references/details.md。如果上方的导航摘要无法满足需求，请阅读该文件。

最佳实践摘要

1. 尽早验证 - 在开销较大的操作之前检查输入
2. 使用具体的异常 - 使用 ValueError、TypeError，而非通用的 Exception
3. 包含上下文 - 消息应说明问题、原因以及如何修复
4. 在边界处转换类型 - 尽早将字符串解析为枚举或领域类型
5. 链接异常 - 使用 raise ... from e 保留调试信息
6. 处理部分失败 - 不要因单个项目出错而中止整个批次
7. 使用 Pydantic - 用于复杂的输入验证并生成结构化错误
8. 记录失败模式 - 文档字符串应列出可能发生的异常
9. 记录带上下文的日志 - 包含 ID、计数和其他调试信息
10. 测试错误路径 - 验证异常是否按预期抛出

工作流程

Step 1: 需求分析

理解项目需求和技术约束

Step 2: 架构设计

设计系统架构和组件划分

Step 3: 实现指导

提供具体的实现建议和代码模式

Step 4: 代码审查

审查代码质量和最佳实践遵循情况

Step 5: 优化建议

提供性能优化和改进建议

注意事项

1. 过度设计

避免在简单场景中使用复杂的设计模式

2. 性能忽视

不要忽视性能优化，特别是在生产环境中

3. 安全考虑

始终考虑安全性和数据保护

4. 测试覆盖

确保有足够的测试覆盖，特别是边界情况

5. 文档维护

保持文档与代码同步更新