datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0025-exception-handling.md

架构决策记录 - 异常处理机制完善

背景

在实现 Salesforce 元数据拉取和部署功能后，需要完善异常处理机制，捕获和处理各种异常情况，提供友好的错误提示和恢复机制。当前系统异常处理机制不完善，无法有效捕获和处理异常，无法提供友好的错误提示和恢复机制。

面临的问题：

1. 无法有效捕获各种异常情况
2. 无法对异常进行分类
3. 无法对不同类型的异常进行不同的处理
4. 无法从异常中恢复
5. 无法及时发送异常告警
6. 无法记录异常的详细信息

约束条件：

1. 必须基于现有的 Spring Boot 3 + Vue 3 技术栈
2. 必须遵循 Authentication.canvas 中定义的架构和调用关系
3. 必须在 datai-salesforce-metadata 模块下实现
4. 必须使用 MyBatis Plus 作为持久层框架
5. 异常处理性能必须满足要求，不能影响系统响应
6. 必须使用 SessionManager 进行会话管理和自动重新登录
7. 必须使用现有的认证模块进行 OAuth 认证
8. 必须使用现有的集成核心功能进行 API 调用

相关的业务需求：

1. 异常捕获 - 捕获各种异常情况
2. 异常分类 - 对异常进行分类
3. 异常处理 - 对不同类型的异常进行不同的处理
4. 异常恢复 - 支持从异常中恢复
5. 异常告警 - 异常发生时发送告警通知
6. 异常日志 - 记录异常的详细信息

决策

1. 异常捕获方案

决策: 使用 try-catch 捕获异常，使用全局异常处理器统一处理异常。

理由:

• try-catch 是 Java 标准的异常捕获机制，简单可靠
• 全局异常处理器可以统一处理异常，避免重复代码
• Spring Boot 提供了 @ControllerAdvice 和 @ExceptionHandler 注解，方便实现全局异常处理
• 支持自定义异常和异常信息

实现方案:

• 创建自定义异常类，包括 NetworkException、ApiCallException、FileOperationException、DatabaseOperationException、BusinessLogicException
• 创建全局异常处理器，使用 @ControllerAdvice 和 @ExceptionHandler 注解
• 捕获网络异常、API 调用异常、文件操作异常、数据库操作异常、业务逻辑异常
• 使用 try-catch 捕获异常，使用全局异常处理器统一处理异常
• 支持异常信息封装和异常信息返回

2. 异常分类方案

决策: 使用异常类型和异常代码进行分类，使用枚举类型管理异常类型。

理由:

• 异常类型可以清晰地区分不同类型的异常
• 异常代码可以更细粒度地区分异常
• 枚举类型可以统一管理异常类型，提高代码可读性
• 支持按异常类型、异常级别、异常来源分类

实现方案:

• 创建 ExceptionType 枚举，定义异常类型（NETWORK、API_CALL、FILE_OPERATION、DATABASE_OPERATION、BUSINESS_LOGIC）
• 创建 ExceptionLevel 枚举，定义异常级别（INFO、WARN、ERROR、FATAL）
• 创建 ExceptionSource 枚举，定义异常来源（METADATA_RETRIEVE、METADATA_DEPLOY、FILE_STORAGE、DATABASE）
• 使用异常类型和异常代码进行分类
• 使用枚举类型管理异常类型、异常级别、异常来源

3. 异常处理方案

决策: 使用重试机制处理可恢复异常，使用事务回滚处理数据库异常。

理由:

• 重试机制可以自动处理可恢复异常，提高系统稳定性
• 事务回滚可以确保数据库操作的原子性，避免数据不一致
• Spring Retry 提供了 @Retryable 注解，方便实现重试机制
• Spring Transaction 提供了 @Transactional 注解，方便实现事务回滚

实现方案:

• 使用 Spring Retry 的 @Retryable 注解实现重试机制
• 支持网络异常重试、API 调用异常重试
• 使用 Spring Transaction 的 @Transactional 注解实现事务回滚
• 支持数据库操作异常回滚
• 使用 try-catch 捕获异常，使用重试机制处理可恢复异常
• 支持文件操作异常恢复、业务逻辑异常提示
• 支持异常处理逻辑配置

4. 异常恢复方案

决策: 使用状态机管理恢复过程，使用恢复点记录恢复状态。

理由:

• 状态机可以清晰地管理恢复过程，避免恢复混乱
• 恢复点可以记录恢复状态，支持断点恢复
• 支持自动恢复和手动恢复
• 恢复操作安全可靠

实现方案:

• 创建 RecoveryPoint 实体类，存储恢复点信息
• 创建 RecoveryPointMapper 接口，使用 MyBatis Plus 的 BaseMapper
• 创建 IRecoveryService 服务接口
• 创建 RecoveryServiceImpl 服务实现
• 使用状态机管理恢复过程
• 使用恢复点记录恢复状态
• 支持自动恢复和手动恢复
• 支持恢复点设置和恢复点查询
• 支持恢复操作安全可靠
• 支持恢复日志记录完整

5. 异常告警方案

决策: 使用消息队列发送告警，使用配置文件管理告警配置。

理由:

• 消息队列可以异步发送告警，不影响系统响应
• 配置文件可以灵活管理告警配置
• 支持多种告警方式（邮件、短信、钉钉等）
• 支持告警配置和告警去重

实现方案:

• 创建 ExceptionAlarm 实体类，存储异常告警信息
• 创建 ExceptionAlarmMapper 接口，使用 MyBatis Plus 的 BaseMapper
• 创建 IExceptionAlarmService 服务接口
• 创建 ExceptionAlarmServiceImpl 服务实现
• 使用消息队列发送告警，异步处理告警发送
• 使用配置文件管理告警配置，支持多种告警方式
• 支持邮件告警、短信告警、钉钉告警等
• 支持告警配置，包括告警开关、告警方式、告警接收人等
• 支持告警去重，避免重复告警

6. 异常日志方案

决策: 使用日志框架记录异常日志，使用 MyBatis Plus 实现异常日志查询。

理由:

• 日志框架（如 Log4j2、SLF4J）提供了丰富的日志功能，易于使用和维护
• 支持多种日志级别（INFO、WARN、ERROR），便于日志分类和管理
• 支持日志格式化和日志输出到多种目标（文件、数据库、消息队列等）
• MyBatis Plus 提供了丰富的查询方法，简化查询逻辑

实现方案:

• 创建 ExceptionLog 实体类，存储异常日志信息
• 创建 ExceptionLogMapper 接口，使用 MyBatis Plus 的 BaseMapper
• 创建 IExceptionLogService 服务接口
• 创建 ExceptionLogServiceImpl 服务实现
• 使用日志框架记录异常日志，使用 SLF4J 和 Log4j2
• 使用 MyBatis Plus 实现异常日志查询
• 支持异常日志信息完整详细
• 支持异常日志查询和异常日志导出
• 支持异常日志不影响系统性能

备选方案

方案 1: 使用 AOP 实现异常捕获

优点:

• AOP 可以统一捕获异常，避免重复代码
• 可以灵活地定义异常捕获的切面
• 支持异常捕获的动态配置

缺点:

• AOP 实现复杂，需要维护切面
• 增加系统复杂度
• 可能影响系统性能

评估: 不采用，实现复杂，增加系统复杂度

方案 2: 使用断路器模式实现异常处理

优点:

• 断路器模式可以防止级联故障
• 可以自动熔断和恢复
• 支持降级处理

缺点:

• 断路器模式实现复杂，需要维护断路器状态
• 增加系统复杂度
• 需要额外的依赖（如 Hystrix、Resilience4j）

评估: 不采用，实现复杂，增加系统复杂度

方案 3: 使用自定义异常处理器实现异常处理

优点:

• 自定义异常处理器可以灵活地处理异常
• 可以自定义异常处理逻辑
• 可以自定义异常信息返回

缺点:

• 自定义异常处理器实现复杂，需要维护异常处理器
• 增加系统复杂度
• 可能与 Spring Boot 的异常处理器冲突

评估: 不采用，实现复杂，增加系统复杂度

影响

系统架构影响

• 新增 exception 包，包含异常处理相关的服务、控制器、DTO、实体、Mapper、工具类
• 新增自定义异常类，包括 NetworkException、ApiCallException、FileOperationException、DatabaseOperationException、BusinessLogicException
• 新增全局异常处理器，使用 @ControllerAdvice 和 @ExceptionHandler 注解
• 新增 ExceptionType、ExceptionLevel、ExceptionSource 枚举
• 新增 RecoveryPoint、ExceptionAlarm、ExceptionLog 实体类，新增 recovery_point、exception_alarm、exception_log 数据库表
• 新增 IRecoveryService、IExceptionAlarmService、IExceptionLogService 服务接口
• 新增 RecoveryServiceImpl、ExceptionAlarmServiceImpl、ExceptionLogServiceImpl 服务实现
• 新增 RecoveryController、ExceptionAlarmController、ExceptionLogController 控制器

开发流程影响

• 需要开发异常处理相关的服务、控制器、DTO、实体、Mapper、工具类
• 需要创建数据库表和索引
• 需要配置重试机制和事务回滚
• 需要配置消息队列和告警配置
• 需要编写单元测试和集成测试

运维管理影响

• 需要监控异常发生情况
• 需要处理异常告警
• 需要定期清理过期的异常日志
• 需要监控异常处理性能

风险

技术风险

• 异常捕获风险: 异常捕获不完善可能导致异常遗漏
  • 缓解措施: 使用 try-catch 捕获异常，使用全局异常处理器统一处理异常，记录异常捕获日志
• 异常处理风险: 异常处理不当可能导致系统崩溃
  • 缓解措施: 使用重试机制处理可恢复异常，使用事务回滚处理数据库异常，记录异常处理日志
• 恢复风险: 恢复操作失败可能导致无法恢复
  • 缓解措施: 使用状态机管理恢复过程，使用恢复点记录恢复状态，记录恢复操作日志，支持恢复操作重试
• 告警风险: 告警发送失败可能导致无法及时发现问题
  • 缓解措施: 使用消息队列异步发送告警，记录告警发送日志，支持告警重试
• 日志风险: 异常日志过多可能占用大量存储空间
  • 缓解措施: 定期清理过期的异常日志，使用日志压缩，使用日志归档

业务风险

• 异常处理失败风险: 异常处理失败可能导致系统崩溃
  • 缓解措施: 监控异常处理服务，支持异常处理服务重启，记录异常处理日志
• 恢复操作失败风险: 恢复操作失败可能导致无法恢复
  • 缓解措施: 监控恢复操作，支持恢复操作重试，记录恢复操作日志

实施风险

• 开发周期风险: 异常处理机制完善开发周期可能较长
  • 缓解措施: 分阶段实施，优先实现核心功能，逐步完善
• 测试风险: 异常处理机制完善测试可能较为复杂
  • 缓解措施: 编写详细的测试用例，使用自动化测试，进行充分的测试

回滚策略

如果决策实施后出现问题，可以采取以下回滚策略：

1. 禁用异常处理功能: 通过配置文件禁用异常处理功能，不影响系统运行
2. 回滚异常处理代码: 回滚异常处理相关的代码，恢复到之前的版本
3. 回滚数据库表: 删除异常处理相关的数据库表，恢复到之前的数据库结构
4. 回滚配置文件: 回滚异常处理相关的配置文件，恢复到之前的配置

验收标准

定义验证该决策有效性的具体标准和测试方法：

1. 功能完整性: 所有异常处理功能能够正常工作

   • 测试方法: 手动测试异常捕获、异常分类、异常处理、异常恢复、异常告警、异常日志

2. 性能指标: 异常处理性能满足要求，不影响系统响应

   • 测试方法: 性能测试，监控异常处理性能，确保不影响系统响应

3. 完整性: 异常信息完整详细，能够追溯异常发生原因

   • 测试方法: 手动测试异常捕获和异常日志，确保异常信息完整详细

4. 代码规范性: 代码符合项目编码规范，有清晰的注释

   • 测试方法: 代码审查，检查代码规范和注释

5. 可维护性: 代码结构清晰，易于扩展和维护

   • 测试方法: 代码审查，检查代码结构和可维护性

6. 可测试性: 代码易于单元测试和集成测试

   • 测试方法: 单元测试和集成测试，确保测试覆盖率高

视觉锚点

Visual Reference

引用 Canvas 的具体节点或快照：

• Authentication.canvas - 相关架构图
• 具体节点: 集成核心 - 提供与Salesforce的各种连接方式
• 具体节点: SessionManager - 会话管理，提供登录服务
• 快照时间: 2026-01-19 00:00:00

Status

• Draft
• Accepted
• Superceded

参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：

• REQ-010-16.md - 异常处理机制完善需求文档
• REQ-010.md - Salesforce元数据拉取和部署主需求文档
• REQ-010-5.md - Metadata API客户端封装需求文档
• REQ-010-6.md - 元数据拉取核心功能需求文档
• REQ-010-8.md - 元数据部署核心功能需求文档
• metadata-module.md - Salesforce Metadata API 模块说明（唯一真源）
• index.md - Salesforce SOAP API Java 客户端参考文档（唯一真源）