4. 数据源错误捕获策略：try-catch 在数据层的最佳实践、连接池异常处理、重试机制与熔断设计

在报表系统中，数据源错误是最高频、影响面最广的异常类型。本章聚焦数据层的防御性编程，从 try-catch 边界、连接池异常处理、重试机制与熔断设计四个维度，构建企业级报表的数据源韧性架构。

4.1 try-catch 在数据层的最佳实践

数据层的 try-catch 不是简单的“捕获-打印-抛”，而是需要明确捕获粒度、异常包装与资源释放三个关键点。

4.1.1 捕获粒度：按操作单元而非按行

错误的捕获粒度直接影响问题定位效率。推荐以一次数据库交互（一个查询/一个事务）为最小捕获单元。

4.1.2 异常包装：保留根因与上下文

数据层异常必须包装为领域异常，同时保留原始 SQL、参数值和数据库错误码。

// 推荐的数据层异常包装模式
public class DataSourceException extends RuntimeException {
    private final String sql;
    private final Map<String, Object> params;
    private final String dbErrorCode;

    public DataSourceException(String message, Throwable cause,
                               String sql, Map<String, Object> params) {
        super(message, cause);
        this.sql = sql;
        this.params = params;
        this.dbErrorCode = extractDbErrorCode(cause);
    }

    // 保留原始 SQL 和参数，方便报表运维人员直接重放
    public String toDiagnosticString() {
        return String.format("[SQL: %s] [Params: %s] [DB Code: %s] %s",
                sql, params, dbErrorCode, getMessage());
    }
}

4.1.3 资源释放：try-with-resources 强制闭环

报表系统常因连接未释放导致连接池耗尽。Java 7+ 必须使用 try-with-resources 确保 Connection、Statement、ResultSet 自动关闭。

// 强制使用 try-with-resources，杜绝 finally 遗漏
public List<ReportRow> queryReport(String sql, Map<String, Object> params) {
    String cacheKey = buildCacheKey(sql, params);
    // 先查缓存
    List<ReportRow> cached = cacheManager.get(cacheKey);
    if (cached != null) return cached;

    try (Connection conn = dataSource.getConnection();
         PreparedStatement ps = conn.prepareStatement(sql)) {
        setParams(ps, params);
        try (ResultSet rs = ps.executeQuery()) {
            List<ReportRow> result = mapResultSet(rs);
            cacheManager.put(cacheKey, result, Duration.ofMinutes(5));
            return result;
        }
    } catch (SQLException e) {
        throw new DataSourceException("报表查询失败", e, sql, params);
    }
}

4.2 连接池异常处理

连接池是数据源的第一道防线。常见的连接池异常包括：连接泄漏、连接超时、连接池满、无效连接。

4.2.1 连接池关键参数与异常映射

4.2.2 连接池健康检查策略

HikariCP 是目前企业级报表系统的主流选择。推荐的健康检查配置：

// HikariCP 生产级配置示例
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:mysql://report-db:3306/report");
config.setUsername("report_user");
config.setPassword("encrypted_password");

// 核心参数
config.setMaximumPoolSize(20);          // 最大连接数，根据并发报表数调整
config.setMinimumIdle(5);               // 最小空闲连接
config.setIdleTimeout(300000);          // 5分钟空闲回收
config.setMaxLifetime(600000);          // 10分钟强制回收，避免数据库端断开
config.setConnectionTimeout(5000);      // 获取连接超时5秒
config.setLeakDetectionThreshold(60000);// 60秒未归还视为泄漏

// 健康检查
config.setConnectionTestQuery("SELECT 1");
config.setValidationTimeout(3000);      // 验证超时3秒
config.setKeepaliveTime(60000);         // 每60秒发送心跳

4.3 重试机制设计

重试不是简单的“失败就再来一次”，必须考虑幂等性、退避策略和重试次数上限。

4.3.1 可重试与不可重试的异常分类

4.3.2 指数退避 + 抖动实现

报表系统的高峰期（如月末结算），大量报表同时重试会导致“惊群效应”。必须引入抖动（jitter）分散重试时间。

// 带抖动的指数退避重试器
public class RetryWithJitter {
    private final int maxRetries = 3;
    private final long baseDelayMs = 1000; // 基础延迟1秒

    public <T> T executeWithRetry(Supplier<T> operation, String operationName) {
        Exception lastException = null;
        for (int attempt = 0; attempt <= maxRetries; attempt++) {
            try {
                return operation.get();
            } catch (Exception e) {
                lastException = e;
                if (attempt == maxRetries || !isRetryable(e)) {
                    break;
                }
                long delay = computeDelayWithJitter(attempt);
                log.warn("操作 [{}] 第 {} 次失败，{}ms 后重试: {}",
                        operationName, attempt + 1, delay, e.getMessage());
                sleep(delay);
            }
        }
        throw new DataSourceException("操作 [" + operationName + "] 重试 " + maxRetries + " 次后仍失败",
                lastException, "", Map.of());
    }

    private long computeDelayWithJitter(int attempt) {
        // 指数退避: 1s, 2s, 4s
        long exponentialDelay = baseDelayMs * (long) Math.pow(2, attempt);
        // 抖动: 在 [0, exponentialDelay) 范围内随机
        long jitter = (long) (Math.random() * exponentialDelay);
        return exponentialDelay + jitter;
    }

    private boolean isRetryable(Exception e) {
        return e instanceof SQLTransientException
                || e instanceof DeadlockLoserDataAccessException
                || e.getMessage().contains("timeout");
    }
}

4.4 熔断设计

当数据源持续异常时，重试只会加剧系统负载。熔断器在错误率达到阈值时快速失败，保护下游系统不被拖垮。

4.4.1 熔断器状态机

4.4.2 基于 Resilience4j 的熔断器集成

企业级报表系统推荐使用 Resilience4j 作为熔断器实现，轻量且与 Spring 生态无缝集成。

// Resilience4j 熔断器配置
CircuitBreakerConfig config = CircuitBreakerConfig.custom()
    .failureRateThreshold(50)                    // 50% 错误率触发熔断
    .slidingWindowSize(10)                       // 统计最近 10 次调用
    .minimumNumberOfCalls(5)                     // 最少 5 次调用才开始统计
    .waitDurationInOpenState(Duration.ofSeconds(30)) // 熔断 30 秒后进入半开
    .permittedNumberOfCallsInHalfOpenState(3)    // 半开状态允许 3 次试探
    .recordExceptions(SQLException.class, DataSourceException.class)
    .ignoreExceptions(BadSqlGrammarException.class) // 语法错误不触发熔断
    .build();

CircuitBreaker circuitBreaker = CircuitBreaker.of("reportDataSource", config);

// 使用熔断器包装数据源调用
public List<ReportRow> safeQueryReport(String sql, Map<String, Object> params) {
    return circuitBreaker.executeSupplier(() -> {
        return queryReport(sql, params);
    });
}

4.4.3 熔断后的降级策略

熔断不是终点，必须提供降级方案，保证报表系统在数据源不可用时仍能返回有意义的响应。

4.5 本章小结

数据源错误捕获策略的核心原则：

• try-catch 粒度：按操作单元捕获，保留 SQL 和参数上下文，使用 try-with-resources 强制释放资源。
• 连接池管理：合理配置 maxLifetime、leakDetectionThreshold、connectionTestQuery，监控 activeConnections 和 evictedConnections。
• 重试机制：只重试可恢复异常（超时、死锁），使用指数退避 + 抖动避免惊群，设置最大重试次数。
• 熔断设计：基于滑动窗口统计错误率，熔断后提供缓存/静态/空/异步四级降级策略，保护下游系统稳定性。