📚 课程目录第3章报表数据源错误分类

3. 报表数据源错误分类：典型场景与根因分析

在报表系统的实际运行中，数据源错误是出现频率最高、影响范围最广的一类异常。根据生产环境故障统计，超过 65% 的报表失败事件直接或间接与数据源层相关。本章将围绕四种典型场景——数据库连接失败、查询超时、数据格式不匹配、字段缺失——展开深度剖析，帮助架构师在 Ent 领域边界处建立精准的错误分类与隔离策略。

3.1 错误分类总览

数据源错误可按故障发生阶段分为连接层、执行层和结果层三大类。下表列出了各场景的关键特征与典型根因：

错误类别	所属阶段	典型错误码/消息	常见根因	影响范围
数据库连接失败	连接层	Cannot connect to server / Connection refused	网络中断、认证失效、连接池耗尽、数据库实例宕机	全局性，影响所有依赖该数据源的报表
查询超时	执行层	Query timeout expired / Statement cancelled	SQL 未优化、数据量暴增、锁等待、资源争抢	局部性，通常影响特定报表或时间段
数据格式不匹配	结果层	Data truncation / Type conversion failed	字段类型变更、编码不一致、空值处理不当	局部性，影响特定字段或行记录
字段缺失	结果层	Column not found / Unknown column	DDL 变更未同步、视图定义过期、权限不足	局部性，影响特定列或派生字段

架构提示：在 Ent 领域边界处，建议将连接层错误视为基础设施异常，由中间件层统一捕获并触发熔断；执行层和结果层错误则应映射为领域业务异常，由报表编排引擎按报表级别进行重试或降级。

3.2 场景一：数据库连接失败

数据库连接失败是破坏力最强的数据源错误。一旦发生，所有依赖该数据源的报表将同时进入失败状态。典型表现包括：

网络层面：DNS 解析失败、防火墙拦截、VPN 隧道断开。
认证层面：密码过期、白名单变更、SSL 证书失效。
资源层面：连接池最大连接数耗尽、数据库端 max_connections 达到上限。
实例层面：数据库进程崩溃、主备切换期间服务不可用。

避坑指南：不要将连接失败直接暴露给报表用户。应在 Ent 领域边界处设计连接健康检查探针，在报表调度前预检数据源可用性。若连续 3 次探针失败，应自动切换至备用数据源或触发告警。

3.3 场景二：查询超时

查询超时是执行层最常见的错误，其根因往往隐藏在 SQL 执行计划与数据分布的变化中。以下流程图展示了超时错误的典型排查路径：

超时错误的处理策略应区分短期与长期两类：

短期策略：在 Ent 领域边界处设置超时阈值（如 30 秒），超时后自动重试 1 次，重试间隔指数退避。
长期策略：建立 SQL 性能基线，当执行时间偏离基线超过 200% 时，自动触发慢查询日志分析并通知 DBA。

3.4 场景三：数据格式不匹配

数据格式不匹配通常发生在数据源表结构变更后，报表层未及时感知。典型场景包括：

变更类型	示例	报表表现	Ent 边界处理
字段类型变更	VARCHAR(50) → VARCHAR(200)	数据截断异常	在数据接入层做类型校验与截断检测
编码不一致	UTF-8 → GBK	乱码或转换失败	统一编码转换层，报表侧只消费 UTF-8
空值策略变更	NULL → 空字符串	聚合计算异常	在领域层定义空值语义映射规则
精度变化	DECIMAL(10,2) → DECIMAL(12,4)	舍入差异	报表侧使用高精度类型接收，再按业务规则截断

  最佳实践：在 Ent 领域边界处引入数据契约校验。每次报表执行前，对比数据源返回的元数据与报表定义的字段契约。若发现类型或长度不匹配，立即记录错误详情并阻断执行，避免将脏数据写入报表结果集。

3.5 场景四：字段缺失

字段缺失错误往往比格式不匹配更隐蔽，因为 SQL 在语法上可能仍然合法，但结果集中缺少了报表依赖的列。常见根因包括：

DDL 变更未同步：上游表删除了某列，但报表 SQL 仍引用该列。
视图定义过期：数据库视图依赖的基础表结构已变更，视图未刷新。
权限变更：报表账号对某列的 SELECT 权限被撤销。
动态 SQL 错误：拼接 SQL 时条件分支导致某列未被包含。

以下 SVG 展示了字段缺失错误的检测与恢复流程：

3.6 错误分类在 Ent 领域边界中的应用

将上述四种错误场景映射到 Ent 领域边界，可以形成清晰的错误隔离策略：

连接层错误 → 基础设施边界：由数据源适配器统一处理，触发熔断与降级，不进入领域逻辑。
执行层错误 → 应用服务边界：由报表编排服务捕获，执行重试策略或切换数据源。
结果层错误 → 领域模型边界：由领域服务进行数据契约校验，阻断异常数据进入报表结果。

架构决策：建议在 Ent 领域边界处定义统一的 DataSourceError 异常层次结构，包含 ConnectionFailedError、QueryTimeoutError、DataFormatMismatchError、FieldMissingError 四个子类。每个子类携带数据源标识、错误码、上下文元数据，便于上层进行精细化处理。

// Ent 领域边界错误层次结构示例
public abstract class DataSourceError extends RuntimeException {
    private final String dataSourceId;
    private final String errorCode;
    private final Map<String, Object> context;
    // 构造函数与 getter 省略
}

public class ConnectionFailedError extends DataSourceError { /* ... */ }
public class QueryTimeoutError extends DataSourceError { /* ... */ }
public class DataFormatMismatchError extends DataSourceError { /* ... */ }
public class FieldMissingError extends DataSourceError { /* ... */ }

通过这种分类与边界映射，报表系统能够在错误发生时快速定位故障层，并执行对应的恢复策略，从而将数据源错误对最终用户的影响降到最低。