错误处理基础：核心概念、分类与传播机制

在 Ent 报表系统的开发与运维中，错误处理并非简单的“捕获异常并打印日志”。它是一套贯穿数据采集、转换、渲染与交付全链路的系统性工程。理解错误处理的核心概念、掌握错误的分类方法、熟悉错误的传播路径，是构建健壮报表系统的第一道防线。

2.1 错误处理的核心概念

错误处理在 Ent 报表领域包含三个相互关联的层次：错误检测、错误分类与错误响应。下表列出了每个层次的核心定义与典型场景：

2.2 错误分类：语法错误、运行时错误、逻辑错误

从软件工程与 Ent 报表的实际出发，错误可分为三大类。每一类错误的检测时机、影响范围与处理策略均有显著差异。

2.2.1 语法错误

语法错误发生在代码或配置的解析阶段，通常由拼写、格式或结构不符合语言规范引起。在 Ent 报表中，这类错误往往在模板编译期或配置加载期被捕获。

• 常见来源：SQL 语句关键字拼写错误、JSON 配置缺少逗号或花括号、模板表达式（如 {{#each}}）未闭合。
• 处理策略：立即阻断执行，向开发者返回明确的错误位置与期望格式。不应尝试自动修复。
• Ent 报表示例：

// 语法错误示例：模板表达式缺少闭合标签
// 错误：{{#each items}} 缺少 {{/each}}
{
  "reportName": "销售汇总",
  "template": "<table>{{#each items}}<tr><td>{{name}}</td></tr>"
}

2.2.2 运行时错误

运行时错误发生在程序执行期间，通常由外部环境或资源问题引发。这类错误具有不可预测性，是 Ent 报表错误处理的重点关注对象。

• 常见来源：数据库连接超时、API 接口返回 500、磁盘空间不足、内存溢出。
• 处理策略：实施重试机制（带退避策略）、降级服务（如使用本地缓存）、记录完整错误上下文。
• Ent 报表示例：

// 运行时错误示例：数据源连接失败
// 错误信息：Error: connect ECONNREFUSED 192.168.1.100:3306
// 处理：重试 3 次，间隔 2s/4s/8s，若仍失败则使用缓存数据

2.2.3 逻辑错误

逻辑错误是程序语法正确、运行未崩溃，但计算结果或行为不符合预期。这类错误最难发现，通常需要结合业务规则进行校验。

• 常见来源：报表公式中除零错误、聚合函数使用不当（如 SUM 误写为 AVG）、数据过滤条件遗漏。
• 处理策略：引入断言机制、数据校验规则、业务阈值告警。逻辑错误往往需要人工介入修正。
• Ent 报表示例：

// 逻辑错误示例：报表公式除零
// 公式：{{totalRevenue}} / {{totalOrders}}
// 当 totalOrders 为 0 时，结果应为 "N/A" 而非 Infinity
// 修复：添加条件判断 {{#if totalOrders}} ... {{else}} N/A {{/if}}

2.3 错误分类对比表

为了更直观地理解三类错误的差异，下表从多个维度进行了对比：

2.4 错误传播机制

错误传播描述了错误在系统内部如何从发生点传递到处理点。在 Ent 报表系统中，典型的传播路径遵循分层冒泡模式：底层组件（如数据访问层）将错误向上抛给中间层（如报表引擎），最终由顶层（如 API 网关或 UI）统一处理。

上图展示了 Ent 报表系统中错误从数据访问层向上冒泡至 API 网关的典型路径。每一层在捕获错误后，都会附加当前层的上下文信息（如报表 ID、数据源名称、执行时间），然后继续向上传播。这种机制确保了顶层能够获得完整的错误链路，便于定位根因。

2.5 错误传播的三种模式

在实际的 Ent 报表系统中，错误传播并非只有“冒泡”一种方式。根据业务场景的不同，通常采用以下三种模式：

• 冒泡传播（Bubble Propagation）：错误从底层逐层向上传递，每层可添加上下文。适用于关键链路（如报表生成主流程），确保错误不被吞没。
• 短路传播（Short-circuit Propagation）：当检测到不可恢复的错误时，立即中断当前流程并返回错误，不再继续执行后续步骤。适用于数据源连接失败、权限校验不通过等场景。
• 降级传播（Degradation Propagation）：错误发生后，当前层尝试使用备用方案（如缓存数据、默认值）继续执行，并将错误信息记录到日志或附加到最终响应中。适用于非关键数据块加载失败的情况。

2.6 错误传播中的上下文传递

无论采用哪种传播模式，错误上下文（Error Context）的传递都是关键。一个完整的错误上下文应包含以下字段：

在代码实现中，建议使用结构化的错误对象（而非纯字符串）来传递上下文。以下是一个 TypeScript 示例：

// 结构化错误上下文示例
interface ReportErrorContext {
  reportId: string;
  dataSource: string;
  component: string;
  timestamp: Date;
  errorCode: string;
  message: string;
  originalError?: Error;
}

class ReportError extends Error {
  public context: ReportErrorContext;

  constructor(context: ReportErrorContext) {
    super(context.message);
    this.name = 'ReportError';
    this.context = context;
  }
}

// 使用示例
throw new ReportError({
  reportId: 'RPT-2025-00123',
  dataSource: 'sales_mysql_prod',
  component: 'DataFetcher',
  timestamp: new Date(),
  errorCode: 'E_DB_TIMEOUT',
  message: '数据库查询超时（30s）',
  originalError: originalDbError
});

通过结构化的错误上下文，上层组件可以基于 errorCode 决定重试、降级或直接返回错误，同时保留完整的原始错误信息用于日志审计。