311 lines
13 KiB
Markdown
311 lines
13 KiB
Markdown
# 架构决策记录 - 异常处理机制完善
|
||
|
||
## 背景
|
||
|
||
在实现 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 客户端参考文档（唯一真源）
|