11 KiB
11 KiB
架构决策记录 - 详细日志记录和查询
背景
在实现 Salesforce 元数据拉取和部署功能后，需要记录作业的详细执行日志，支持日志查询和导出。当前系统缺乏详细日志记录和查询功能，无法追溯作业的执行过程，无法及时发现和处理作业执行中的问题。
面临的问题：
- 无法记录作业的详细执行日志
- 无法查询作业的执行日志
- 无法导出作业的执行日志
- 无法分析作业的执行日志
约束条件：
- 必须基于现有的 Spring Boot 3 + Vue 3 技术栈
- 必须遵循 Authentication.canvas 中定义的架构和调用关系
- 必须在 datai-salesforce-metadata 模块下实现
- 必须使用 MyBatis Plus 作为持久层框架
- 日志记录和查询性能必须满足要求，不能影响作业执行
相关的业务需求：
- 日志记录 - 记录作业的详细执行日志
- 日志查询 - 查询作业的执行日志
- 日志导出 - 导出作业的执行日志
- 日志分析 - 分析作业的执行日志
决策
1. 日志记录方案
决策: 使用异步日志记录，使用日志框架记录日志。
理由:
- 异步日志记录可以避免阻塞主线程，不影响作业执行性能
- 日志框架（如 Log4j2、SLF4J）提供了丰富的日志功能，易于使用和维护
- 支持多种日志级别（INFO、WARN、ERROR），便于日志分类和管理
- 支持日志格式化和日志输出到多种目标（文件、数据库、消息队列等）
实现方案:
- 创建 LogLevel 枚举，定义日志级别（INFO、WARN、ERROR）
- 创建 OperationLog 实体类，存储操作日志信息
- 创建 OperationLogMapper 接口，使用 MyBatis Plus 的 BaseMapper
- 创建 IOperationLogService 服务接口
- 创建 OperationLogServiceImpl 服务实现
- 使用异步日志记录，使用 @Async 注解实现异步
- 使用日志框架记录日志，使用 SLF4J 和 Log4j2
- 支持记录拉取作业日志、部署作业日志、Quick Deploy 作业日志、Destructive Changes 作业日志
- 支持记录日志级别、日志内容、日志时间、作业ID等信息
2. 日志查询方案
决策: 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，使用分页插件实现分页。
理由:
- MyBatis Plus 的 QueryWrapper 提供了丰富的查询方法，简化多条件查询逻辑
- 分页插件可以方便地实现分页查询
- 支持多种查询条件，包括按作业ID、时间范围、日志级别、关键词等查询
- 查询性能良好，满足查询性能要求
实现方案:
- 创建 ILogQueryService 服务接口
- 创建 LogQueryServiceImpl 服务实现
- 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询
- 使用 MyBatis Plus 的分页插件实现分页查询
- 支持按作业ID查询日志
- 支持按时间范围查询日志
- 支持按日志级别查询日志
- 支持按关键词查询日志
- 支持分页查询
3. 日志导出方案
决策: 使用文件导出库实现日志导出，使用流式处理大文件导出。
理由:
- 文件导出库（如 Apache POI、EasyExcel）提供了丰富的文件导出功能，易于使用和维护
- 支持多种文件格式（文本文件、Excel 文件、CSV 文件）
- 流式处理可以避免内存溢出，支持大文件导出
- 导出性能良好，满足导出性能要求
实现方案:
- 创建 ILogExportService 服务接口
- 创建 LogExportServiceImpl 服务实现
- 使用 Apache POI 实现 Excel 文件导出
- 使用 EasyExcel 实现 Excel 文件导出（推荐，性能更好）
- 使用 Java IO 实现文本文件和 CSV 文件导出
- 使用流式处理大文件导出，避免内存溢出
- 支持导出为文本文件
- 支持导出为 Excel 文件
- 支持导出为 CSV 文件
4. 日志分析方案
决策: 使用聚合查询实现日志统计，使用图表展示分析结果。
理由:
- 聚合查询可以快速统计日志数量，提高查询性能
- 图表可以直观展示分析结果，便于用户理解
- 支持多种分析维度，包括按时间、按日志级别、按作业类型等分析
- 分析结果准确，满足分析准确性要求
实现方案:
- 创建 ILogAnalysisService 服务接口
- 创建 LogAnalysisServiceImpl 服务实现
- 使用 MyBatis Plus 的聚合查询实现日志统计
- 使用 ECharts 或其他图表库展示分析结果
- 支持统计错误日志数量
- 支持统计警告日志数量
- 支持统计信息日志数量
- 支持分析作业执行趋势
- 支持按时间分析日志
- 支持按日志级别分析日志
- 支持按作业类型分析日志
备选方案
方案 1: 使用 ELK Stack 实现日志管理
优点:
- ELK Stack（Elasticsearch、Logstash、Kibana）提供了强大的日志管理和分析功能
- 支持实时日志查询和分析
- 支持大规模日志存储和查询
缺点:
- 实现复杂，需要部署和维护 ELK Stack
- 增加系统复杂度
- 需要额外的服务器资源
评估: 不采用，实现复杂，增加系统复杂度
方案 2: 使用消息队列实现日志收集
优点:
- 消息队列可以异步收集日志，不影响作业执行
- 可以解耦日志记录和日志存储
- 支持分布式日志收集
缺点:
- 实现复杂，需要维护消息队列
- 增加系统复杂度
- 可能出现消息丢失或重复消费
评估: 不采用，实现复杂，增加系统复杂度
方案 3: 使用数据库存储日志
优点:
- 数据库存储简单，易于实现和维护
- 支持结构化查询
- 支持事务和索引
缺点:
- 数据库性能可能受到影响
- 存储空间占用较大
- 不适合大规模日志存储
评估: 采用，结合异步日志记录和分表存储，可以满足需求
影响
系统架构影响
- 新增 log 包，包含日志记录和查询相关的服务、控制器、DTO、实体、Mapper、工具类
- 新增 OperationLog 实体类，新增 operation_log 数据库表
- 新增 IOperationLogService、ILogQueryService、ILogExportService、ILogAnalysisService 服务接口
- 新增 OperationLogServiceImpl、LogQueryServiceImpl、LogExportServiceImpl、LogAnalysisServiceImpl 服务实现
- 新增 LogQueryController、LogExportController、LogAnalysisController 控制器
开发流程影响
- 需要开发日志记录和查询相关的服务、控制器、DTO、实体、Mapper、工具类
- 需要创建数据库表和索引
- 需要配置日志框架和异步日志记录
- 需要编写单元测试和集成测试
运维管理影响
- 需要监控日志记录情况
- 需要定期清理过期的日志
- 需要监控日志存储空间
- 需要监控日志查询性能
风险
技术风险
- 日志记录性能风险: 日志记录性能不佳可能影响作业执行
- 缓解措施: 使用异步日志记录，使用日志框架，优化日志记录频率
- 查询性能风险: 日志查询性能不佳可能影响用户体验
- 缓解措施: 使用索引优化查询，使用分页查询，使用缓存提高查询性能
- 存储空间风险: 日志过多可能占用大量存储空间
- 缓解措施: 定期清理过期的日志，使用日志压缩，使用日志归档
- 导出性能风险: 日志导出性能不佳可能导致导出失败
- 缓解措施: 使用流式处理大文件导出，使用分批导出，使用异步导出
- 分析准确性风险: 日志分析不准确可能导致误判
- 缓解措施: 使用聚合查询，验证分析结果，提供分析结果导出
业务风险
- 日志记录失败风险: 日志记录失败可能导致日志信息丢失
- 缓解措施: 使用异步日志记录，记录日志记录失败日志，支持日志记录重试
- 日志查询失败风险: 日志查询失败可能导致无法追溯作业执行过程
- 缓解措施: 监控日志查询服务，支持日志查询服务重启，记录日志查询日志
实施风险
- 开发周期风险: 日志记录和查询功能开发周期可能较长
- 缓解措施: 分阶段实施，优先实现核心功能，逐步完善
- 测试风险: 日志记录和查询功能测试可能较为复杂
- 缓解措施: 编写详细的测试用例，使用自动化测试，进行充分的测试
回滚策略
如果决策实施后出现问题，可以采取以下回滚策略：
- 禁用日志记录功能: 通过配置文件禁用日志记录功能，不影响作业执行
- 回滚日志记录代码: 回滚日志记录相关的代码，恢复到之前的版本
- 回滚数据库表: 删除日志记录相关的数据库表，恢复到之前的数据库结构
- 回滚配置文件: 回滚日志记录相关的配置文件，恢复到之前的配置
验收标准
定义验证该决策有效性的具体标准和测试方法：
-
功能完整性: 所有日志记录和查询功能能够正常工作
- 测试方法: 手动测试日志记录、日志查询、日志导出、日志分析
-
性能指标: 日志记录和查询性能满足要求，不影响作业执行
- 测试方法: 性能测试，监控日志记录和查询性能，确保不影响作业执行
-
完整性: 日志信息完整详细，能够追溯作业执行过程
- 测试方法: 手动测试日志记录，确保日志信息完整详细
-
代码规范性: 代码符合项目编码规范，有清晰的注释
- 测试方法: 代码审查，检查代码规范和注释
-
可维护性: 代码结构清晰，易于扩展和维护
- 测试方法: 代码审查，检查代码结构和可维护性
-
可测试性: 代码易于单元测试和集成测试
- 测试方法: 单元测试和集成测试，确保测试覆盖率高
视觉锚点
Visual Reference
引用 Canvas 的具体节点或快照：
- Authentication.canvas - 相关架构图
- 具体节点: 集成核心 - 提供与Salesforce的各种连接方式
- 快照时间: 2026-01-19 00:00:00
Status
- Draft
- Accepted
- Superceded
参考资料
列出与该决策相关的参考资料，包括文档、文章或其他资源：
- REQ-010-15.md - 详细日志记录和查询需求文档
- REQ-010.md - Salesforce元数据拉取和部署主需求文档
- REQ-010-6.md - 元数据拉取核心功能需求文档
- REQ-010-8.md - 元数据部署核心功能需求文档
- REQ-010-14.md - 作业执行监控需求文档
- metadata-module.md - Salesforce Metadata API 模块说明（唯一真源）
- index.md - Salesforce SOAP API Java 客户端参考文档（唯一真源）