4、报表错误捕获机制：try-except块的使用、捕获特定异常、捕获所有异常、异常链与异常传播

在报表开发中，错误捕获是保障系统稳定性的第一道防线。Python 的 try-except 机制允许开发者精确控制错误发生时的行为，避免因单个数据源异常导致整个报表管道崩溃。本章将围绕报表场景，系统讲解异常捕获的核心模式与实战技巧。

4.1 try-except 基础结构

一个标准的 try-except 块由三部分组成：尝试执行的代码、异常处理代码、以及可选的清理代码。在报表上下文中，最常见的用法是包裹数据加载与转换逻辑。

try:
    # 尝试加载报表数据源
    df = pd.read_sql(query, connection)
    report_data = transform(df)
except Exception as e:
    # 捕获异常并记录
    logger.error(f"报表数据加载失败: {e}")
    report_data = pd.DataFrame()  # 返回空DataFrame避免下游中断

4.2 捕获特定异常

报表开发中常见的异常类型包括数据库连接失败、文件不存在、数据格式错误等。捕获特定异常可以让处理逻辑更精准，避免掩盖非预期错误。

try:
    with open(report_config_path, 'r') as f:
        config = json.load(f)
except FileNotFoundError:
    logger.warning(f"配置文件 {report_config_path} 不存在，使用默认配置")
    config = DEFAULT_REPORT_CONFIG
except json.JSONDecodeError:
    logger.error(f"配置文件格式错误，请检查 {report_config_path}")
    config = DEFAULT_REPORT_CONFIG
except Exception as e:
    logger.critical(f"未知错误加载配置: {e}")
    raise  # 重新抛出，让上层处理

4.3 捕获所有异常

在某些报表场景中，需要确保即使发生错误，报表也能生成部分结果或优雅降级。此时可以使用捕获所有异常的 except Exception 模式，但必须谨慎使用。

def safe_generate_report(report_id):
    """安全生成报表，任何异常都不会中断主流程"""
    try:
        data = fetch_report_data(report_id)
        chart = render_chart(data)
        pdf = export_to_pdf(chart)
        return pdf
    except Exception as e:
        logger.error(f"报表 {report_id} 生成失败: {e}", exc_info=True)
        # 返回错误报告对象，包含部分可用数据
        return ErrorReport(
            report_id=report_id,
            error_message=str(e),
            partial_data=data if 'data' in locals() else None
        )

4.4 异常链与异常传播

在多层报表处理流程中，原始异常往往需要携带上下文信息向上传播。Python 的异常链机制（raise ... from ...）可以保留完整的错误链路，便于排查根因。

class ReportProcessingError(Exception):
    """报表处理自定义异常"""
    def __init__(self, message, report_id=None, source_error=None):
        super().__init__(message)
        self.report_id = report_id
        self.source_error = source_error

def load_report_data(report_id):
    try:
        raw_data = query_database(report_id)
        return validate_and_clean(raw_data)
    except DatabaseConnectionError as e:
        # 保留原始异常，添加报表上下文
        raise ReportProcessingError(
            f"报表 {report_id} 数据加载失败",
            report_id=report_id,
            source_error=e
        ) from e
    except DataValidationError as e:
        raise ReportProcessingError(
            f"报表 {report_id} 数据校验不通过",
            report_id=report_id,
            source_error=e
        ) from e

4.5 finally 清理与资源释放

报表处理中经常涉及文件句柄、数据库连接、网络会话等资源。无论是否发生异常，finally 块都能确保资源被正确释放，避免资源泄漏。

def export_report_with_cleanup(report_id, output_path):
    conn = None
    file_handle = None
    try:
        conn = create_database_connection()
        file_handle = open(output_path, 'wb')
        data = fetch_report(conn, report_id)
        file_handle.write(data)
        logger.info(f"报表 {report_id} 导出成功")
    except Exception as e:
        logger.error(f"报表导出失败: {e}")
        raise
    finally:
        # 无论成功或失败，都执行清理
        if file_handle:
            file_handle.close()
        if conn:
            conn.close()
        logger.debug("资源清理完成")

4.6 实战：报表管道中的异常处理策略

在完整的报表生成管道中，不同阶段的异常需要采用不同的处理策略。下表总结了各阶段的推荐做法：

def report_pipeline(report_id):
    """完整的报表管道异常处理示例"""
    try:
        # 阶段1：数据源连接（重试机制）
        conn = retry_connection(max_attempts=3)
    except ConnectionError as e:
        logger.critical(f"无法连接数据源: {e}")
        return generate_error_report(report_id, "数据源不可用")

    try:
        # 阶段2：数据提取（部分失败容忍）
        raw_data = extract_data_with_skip(conn, report_id)
    except DataExtractionError as e:
        logger.error(f"数据提取部分失败: {e}")
        raw_data = e.partial_data  # 使用部分数据

    try:
        # 阶段3：数据转换（精确捕获）
        clean_data = transform_data(raw_data)
    except (ValueError, TypeError) as e:
        logger.warning(f"数据转换异常，使用默认值: {e}")
        clean_data = apply_default_values(raw_data)

    try:
        # 阶段4：报表渲染（异常链传播）
        report = render_report(clean_data)
    except Exception as e:
        raise ReportRenderError(f"报表渲染失败: {report_id}") from e

    return report