361 lines
14 KiB
Markdown
361 lines
14 KiB
Markdown
# 会话记录 - 异常处理机制完善
|
||
|
||
## 现状
|
||
|
||
当前项目已经实现了元数据拉取核心功能（REQ-010-6）、元数据部署核心功能（REQ-010-8）、作业执行监控功能（REQ-010-14）和详细日志记录和查询功能（REQ-010-15），需要在此基础上完善异常处理机制，以便捕获和处理各种异常情况，提供友好的错误提示和恢复机制。
|
||
|
||
## 目标
|
||
|
||
完善异常处理机制，包括异常捕获、异常分类、异常处理、异常恢复、异常告警、异常日志。支持捕获和处理各种异常情况，提供友好的错误提示和恢复机制。
|
||
|
||
## 输入链接
|
||
|
||
- [REQ-010-16.md](../requirements/REQ-010-16.md) - 异常处理机制完善需求文档
|
||
- [0025-exception-handling.md](../decisions/adr/0025-exception-handling.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 客户端参考文档（唯一真源）
|
||
|
||
## Prompt 文件
|
||
|
||
- [026-exception-handling.md](../prompts/026-exception-handling.md) - 异常处理机制完善实现提示词
|
||
|
||
## Context Snapshot
|
||
|
||
记录本次会话参考了哪些 Canvas 节点：
|
||
|
||
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
||
- **参考节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **参考节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
- **快照时间**: 2026-01-19 00:00:00
|
||
|
||
## 执行过程
|
||
|
||
### 1. 创建异常类型枚举、异常级别枚举、异常来源枚举
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 ExceptionType 枚举，定义异常类型（NETWORK、API_CALL、FILE_OPERATION、DATABASE_OPERATION、BUSINESS_LOGIC）
|
||
- 创建 ExceptionLevel 枚举，定义异常级别（INFO、WARN、ERROR、FATAL）
|
||
- 创建 ExceptionSource 枚举，定义异常来源（METADATA_RETRIEVE、METADATA_DEPLOY、FILE_STORAGE、DATABASE）
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用枚举管理异常类型、异常级别、异常来源，提高代码的可读性和可维护性
|
||
|
||
### 2. 创建自定义异常类
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 BaseException 基类，存储异常类型、异常级别、异常来源、异常代码
|
||
- 创建 NetworkException 网络异常类
|
||
- 创建 ApiCallException API 调用异常类
|
||
- 创建 FileOperationException 文件操作异常类
|
||
- 创建 DatabaseOperationException 数据库操作异常类
|
||
- 创建 BusinessLogicException 业务逻辑异常类
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用自定义异常类，统一管理异常信息，提高异常处理的规范性
|
||
|
||
### 3. 创建全局异常处理器
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 GlobalExceptionHandler 全局异常处理器
|
||
- 使用 @ControllerAdvice 和 @ExceptionHandler 注解
|
||
- 捕获 BaseException 和 Exception
|
||
- 使用 try-catch 捕获异常，使用全局异常处理器统一处理异常
|
||
- 支持异常信息封装和异常信息返回
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用全局异常处理器，统一处理异常，避免重复代码
|
||
|
||
### 4. 创建异常日志实体类、恢复点实体类、异常告警实体类
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 ExceptionLog 实体类，存储异常日志信息
|
||
- 创建 RecoveryPoint 实体类，存储恢复点信息
|
||
- 创建 ExceptionAlarm 实体类，存储异常告警信息
|
||
- 使用 MyBatis Plus 的 @TableName、@TableId 注解
|
||
- 使用 Lombok 的 @Data 注解
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 MyBatis Plus 的 @TableName、@TableId 注解，简化数据库操作
|
||
- 使用 Lombok 的 @Data 注解，简化代码
|
||
|
||
### 5. 创建异常日志服务接口和实现
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 IExceptionLogService 服务接口
|
||
- 创建 ExceptionLogServiceImpl 服务实现
|
||
- 使用 MyBatis Plus 的 BaseMapper 实现异常日志服务
|
||
- 使用日志框架记录异常日志，使用 SLF4J 和 Log4j2
|
||
- 支持保存异常日志、查询异常日志、查询异常日志列表、删除异常日志、批量删除异常日志
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用日志框架记录异常日志，使用 SLF4J 和 Log4j2
|
||
|
||
### 6. 创建恢复服务接口和实现
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 IRecoveryService 服务接口
|
||
- 创建 RecoveryServiceImpl 服务实现
|
||
- 使用 MyBatis Plus 的 BaseMapper 实现恢复服务
|
||
- 使用状态机管理恢复过程
|
||
- 使用恢复点记录恢复状态
|
||
- 支持创建恢复点、查询恢复点、按作业ID查询恢复点、从恢复点恢复、删除恢复点、批量删除恢复点
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用状态机管理恢复过程，使用恢复点记录恢复状态
|
||
|
||
### 7. 创建异常告警服务接口和实现
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 IExceptionAlarmService 服务接口
|
||
- 创建 ExceptionAlarmServiceImpl 服务实现
|
||
- 使用 MyBatis Plus 的 BaseMapper 实现异常告警服务
|
||
- 使用消息队列发送告警，异步处理告警发送
|
||
- 使用配置文件管理告警配置，支持多种告警方式
|
||
- 支持创建异常告警、查询异常告警、发送异常告警、按异常日志ID查询异常告警、删除异常告警、批量删除异常告警
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用消息队列发送告警，异步处理告警发送，不影响系统响应
|
||
|
||
### 8. 创建控制器
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 ExceptionLogController 控制器，提供 4 个 RESTful API 接口
|
||
- 创建 RecoveryController 控制器，提供 6 个 RESTful API 接口
|
||
- 创建 ExceptionAlarmController 控制器，提供 6 个 RESTful API 接口
|
||
- 使用 Swagger 的 @Tag、@Operation 注解
|
||
- 使用 Lombok 的 @RequiredArgsConstructor 注解
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 RESTful API 接口，保持接口一致性
|
||
- 使用 Swagger 的 @Tag、@Operation 注解，生成 API 文档
|
||
- 使用 Lombok 的 @RequiredArgsConstructor 注解，简化代码
|
||
|
||
### 9. 创建 Mapper 接口
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 ExceptionLogMapper 接口，使用 MyBatis Plus 的 BaseMapper
|
||
- 创建 RecoveryPointMapper 接口，使用 MyBatis Plus 的 BaseMapper
|
||
- 创建 ExceptionAlarmMapper 接口，使用 MyBatis Plus 的 BaseMapper
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 MyBatis Plus 的 BaseMapper，简化数据库操作
|
||
|
||
### 10. 创建单元测试
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 ExceptionLogServiceImplTest 单元测试
|
||
- 创建 RecoveryServiceImplTest 单元测试
|
||
- 创建 ExceptionAlarmServiceImplTest 单元测试
|
||
- 创建 GlobalExceptionHandlerTest 单元测试
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 使用 Spring Boot Test 框架，简化测试代码
|
||
|
||
### 11. 创建数据库表
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 创建 datai_exception_log 表，存储异常日志信息
|
||
- 创建 datai_recovery_point 表，存储恢复点信息
|
||
- 创建 datai_exception_alarm 表，存储异常告警信息
|
||
- 为 exception_type、exception_level、exception_source、exception_time 字段创建索引
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 为常用查询字段创建索引，提高查询性能
|
||
|
||
### 12. 更新配置文件
|
||
|
||
**执行时间**: 2026-01-19 00:00:00
|
||
|
||
**操作**:
|
||
- 更新 application.yml，添加重试机制配置
|
||
- 添加 exception-handling 配置项，包括重试次数、重试间隔、告警配置等
|
||
|
||
**遇到的问题**:
|
||
- 无
|
||
|
||
**关键决策**:
|
||
- 添加重试机制配置，支持灵活配置
|
||
- 添加 exception-handling 配置项，支持灵活配置
|
||
|
||
## 关键产出
|
||
|
||
记录本次会话的关键产出，例如：
|
||
|
||
- 生成的代码文件:
|
||
- ExceptionType 枚举 - 异常类型枚举
|
||
- ExceptionLevel 枚举 - 异常级别枚举
|
||
- ExceptionSource 枚举 - 异常来源枚举
|
||
- BaseException 基类 - 自定义异常基类
|
||
- NetworkException 网络异常类 - 网络异常类
|
||
- ApiCallException API 调用异常类 - API 调用异常类
|
||
- FileOperationException 文件操作异常类 - 文件操作异常类
|
||
- DatabaseOperationException 数据库操作异常类 - 数据库操作异常类
|
||
- BusinessLogicException 业务逻辑异常类 - 业务逻辑异常类
|
||
- GlobalExceptionHandler 全局异常处理器 - 全局异常处理器
|
||
- ExceptionLog 实体类 - 异常日志实体类
|
||
- RecoveryPoint 实体类 - 恢复点实体类
|
||
- ExceptionAlarm 实体类 - 异常告警实体类
|
||
- ExceptionLogMapper 接口 - 异常日志 Mapper 接口
|
||
- RecoveryPointMapper 接口 - 恢复点 Mapper 接口
|
||
- ExceptionAlarmMapper 接口 - 异常告警 Mapper 接口
|
||
- IExceptionLogService 服务接口 - 异常日志服务接口
|
||
- ExceptionLogServiceImpl 服务实现 - 异常日志服务实现
|
||
- IRecoveryService 服务接口 - 恢复服务接口
|
||
- RecoveryServiceImpl 服务实现 - 恢复服务实现
|
||
- IExceptionAlarmService 服务接口 - 异常告警服务接口
|
||
- ExceptionAlarmServiceImpl 服务实现 - 异常告警服务实现
|
||
- ExceptionLogController 控制器 - 异常日志控制器
|
||
- RecoveryController 控制器 - 恢复控制器
|
||
- ExceptionAlarmController 控制器 - 异常告警控制器
|
||
- 单元测试 - ExceptionLogServiceImplTest、RecoveryServiceImplTest、ExceptionAlarmServiceImplTest、GlobalExceptionHandlerTest
|
||
- 更新的文档:
|
||
- index.md
|
||
- 创建的文档:
|
||
- 0025-exception-handling.md
|
||
- 026-exception-handling.md
|
||
- 20260119-exception-handling.md
|
||
- 解决的问题:
|
||
- 异常捕获问题 - 使用 try-catch 捕获异常，使用全局异常处理器统一处理异常
|
||
- 异常分类问题 - 使用异常类型和异常代码进行分类，使用枚举类型管理异常类型
|
||
- 异常处理问题 - 使用重试机制处理可恢复异常，使用事务回滚处理数据库异常
|
||
- 异常恢复问题 - 使用状态机管理恢复过程，使用恢复点记录恢复状态
|
||
- 异常告警问题 - 使用消息队列发送告警，使用配置文件管理告警配置
|
||
- 异常日志问题 - 使用日志框架记录异常日志，使用 MyBatis Plus 实现异常日志查询
|
||
- 达成的共识:
|
||
- 使用 try-catch 捕获异常，使用全局异常处理器统一处理异常
|
||
- 使用异常类型和异常代码进行分类，使用枚举类型管理异常类型
|
||
- 使用重试机制处理可恢复异常，使用事务回滚处理数据库异常
|
||
- 使用状态机管理恢复过程，使用恢复点记录恢复状态
|
||
- 使用消息队列发送告警，使用配置文件管理告警配置
|
||
- 使用日志框架记录异常日志，使用 MyBatis Plus 实现异常日志查询
|
||
|
||
## 质疑与替代方案
|
||
|
||
记录在执行过程中提出的质疑和考虑的替代方案：
|
||
|
||
- 质疑：是否需要使用 AOP 实现异常捕获？
|
||
- 替代方案：使用 AOP 实现异常捕获
|
||
- 评估：AOP 可以统一捕获异常，避免重复代码，可以灵活地定义异常捕获的切面，支持异常捕获的动态配置，但 AOP 实现复杂，需要维护切面，增加系统复杂度，可能影响系统性能，不采用
|
||
|
||
- 质疑：是否需要使用断路器模式实现异常处理？
|
||
- 替代方案：使用断路器模式实现异常处理
|
||
- 评估：断路器模式可以防止级联故障，可以自动熔断和恢复，支持降级处理，但断路器模式实现复杂，需要维护断路器状态，增加系统复杂度，需要额外的依赖（如 Hystrix、Resilience4j），不采用
|
||
|
||
- 质疑：是否需要使用自定义异常处理器实现异常处理？
|
||
- 替代方案：使用自定义异常处理器实现异常处理
|
||
- 评估：自定义异常处理器可以灵活地处理异常，可以自定义异常处理逻辑，可以自定义异常信息返回，但自定义异常处理器实现复杂，需要维护异常处理器，增加系统复杂度，可能与 Spring Boot 的异常处理器冲突，不采用
|
||
|
||
## 结论
|
||
|
||
总结本次会话的结果，包括：
|
||
|
||
- 完成的工作:
|
||
- 实现了异常捕获功能
|
||
- 实现了异常分类功能
|
||
- 实现了异常处理功能
|
||
- 实现了异常恢复功能
|
||
- 实现了异常告警功能
|
||
- 实现了异常日志功能
|
||
- 创建了完整的单元测试
|
||
- 创建了数据库表
|
||
- 更新了配置文件
|
||
- 达成的目标:
|
||
- 所有异常处理功能均已实现
|
||
- 代码符合项目编码规范，有清晰的注释
|
||
- 代码结构清晰，易于扩展和维护
|
||
- 代码易于单元测试和集成测试
|
||
- 后续的行动计划:
|
||
- 进行集成测试，确保功能正常
|
||
- 进行性能测试，确保性能满足要求
|
||
- 编写用户文档，说明如何使用异常处理功能
|
||
- 需要跟进的事项:
|
||
- 监控异常发生情况
|
||
- 处理异常告警
|
||
- 定期清理过期的异常日志
|
||
- 监控异常处理性能
|
||
|
||
## Design Update
|
||
|
||
- [x] 是否需要更新 Canvas?
|
||
- [ ] Authentication.canvas - 需要添加异常处理机制完善功能相关的节点
|
||
- [ ] 其他 Canvas 文件: 无
|
||
|
||
## 复现步骤
|
||
|
||
提供复现本次会话结果的具体步骤：
|
||
|
||
1. 创建 ExceptionType、ExceptionLevel、ExceptionSource 枚举
|
||
2. 创建 BaseException 基类和自定义异常类
|
||
3. 创建 GlobalExceptionHandler 全局异常处理器
|
||
4. 创建 ExceptionLog、RecoveryPoint、ExceptionAlarm 实体类
|
||
5. 创建 ExceptionLogMapper、RecoveryPointMapper、ExceptionAlarmMapper 接口
|
||
6. 创建 IExceptionLogService 服务接口和 ExceptionLogServiceImpl 服务实现
|
||
7. 创建 IRecoveryService 服务接口和 RecoveryServiceImpl 服务实现
|
||
8. 创建 IExceptionAlarmService 服务接口和 ExceptionAlarmServiceImpl 服务实现
|
||
9. 创建 ExceptionLogController、RecoveryController、ExceptionAlarmController 控制器
|
||
10. 创建单元测试
|
||
11. 创建数据库表 datai_exception_log、datai_recovery_point、datai_exception_alarm
|
||
12. 更新配置文件 application.yml
|
||
13. 运行单元测试，确保所有测试通过
|
||
14. 进行集成测试，确保功能正常
|
||
15. 进行性能测试，确保性能满足要求
|