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

## 背景

在实现 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](../../Authentication.canvas) - 相关架构图
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
- **具体节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
- **快照时间**: 2026-01-19 00:00:00

### Status

- [x] Draft
- [ ] Accepted
- [ ] Superceded

## 参考资料

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

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