Kris
2e6f087732
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段 - 创建ADR文档：0026-performance-optimization.md - 创建Prompt文档：027-performance-optimization.md - 创建会话记录：20260119-performance-optimization.md - 创建变更记录：20260119-performance-optimization.md - 创建复盘报告：20260119-performance-optimization-retro.md - 更新index.md和CHANGELOG.md - 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段 - 更新ADR文档：0011-entity-mapper-create.md - 创建Prompt文档：002-entity-mapper-create.md - 更新index.md 所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
268 lines
11 KiB
Markdown
268 lines
11 KiB
Markdown
# 架构决策记录 - 详细日志记录和查询
|
||
|
||
## 背景
|
||
|
||
在实现 Salesforce 元数据拉取和部署功能后，需要记录作业的详细执行日志，支持日志查询和导出。当前系统缺乏详细日志记录和查询功能，无法追溯作业的执行过程，无法及时发现和处理作业执行中的问题。
|
||
|
||
面临的问题：
|
||
1. 无法记录作业的详细执行日志
|
||
2. 无法查询作业的执行日志
|
||
3. 无法导出作业的执行日志
|
||
4. 无法分析作业的执行日志
|
||
|
||
约束条件：
|
||
1. 必须基于现有的 Spring Boot 3 + Vue 3 技术栈
|
||
2. 必须遵循 Authentication.canvas 中定义的架构和调用关系
|
||
3. 必须在 datai-salesforce-metadata 模块下实现
|
||
4. 必须使用 MyBatis Plus 作为持久层框架
|
||
5. 日志记录和查询性能必须满足要求，不能影响作业执行
|
||
|
||
相关的业务需求：
|
||
1. 日志记录 - 记录作业的详细执行日志
|
||
2. 日志查询 - 查询作业的执行日志
|
||
3. 日志导出 - 导出作业的执行日志
|
||
4. 日志分析 - 分析作业的执行日志
|
||
|
||
## 决策
|
||
|
||
### 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、工具类
|
||
- 需要创建数据库表和索引
|
||
- 需要配置日志框架和异步日志记录
|
||
- 需要编写单元测试和集成测试
|
||
|
||
### 运维管理影响
|
||
|
||
- 需要监控日志记录情况
|
||
- 需要定期清理过期的日志
|
||
- 需要监控日志存储空间
|
||
- 需要监控日志查询性能
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
|
||
- **日志记录性能风险**: 日志记录性能不佳可能影响作业执行
|
||
- **缓解措施**: 使用异步日志记录，使用日志框架，优化日志记录频率
|
||
- **查询性能风险**: 日志查询性能不佳可能影响用户体验
|
||
- **缓解措施**: 使用索引优化查询，使用分页查询，使用缓存提高查询性能
|
||
- **存储空间风险**: 日志过多可能占用大量存储空间
|
||
- **缓解措施**: 定期清理过期的日志，使用日志压缩，使用日志归档
|
||
- **导出性能风险**: 日志导出性能不佳可能导致导出失败
|
||
- **缓解措施**: 使用流式处理大文件导出，使用分批导出，使用异步导出
|
||
- **分析准确性风险**: 日志分析不准确可能导致误判
|
||
- **缓解措施**: 使用聚合查询，验证分析结果，提供分析结果导出
|
||
|
||
### 业务风险
|
||
|
||
- **日志记录失败风险**: 日志记录失败可能导致日志信息丢失
|
||
- **缓解措施**: 使用异步日志记录，记录日志记录失败日志，支持日志记录重试
|
||
- **日志查询失败风险**: 日志查询失败可能导致无法追溯作业执行过程
|
||
- **缓解措施**: 监控日志查询服务，支持日志查询服务重启，记录日志查询日志
|
||
|
||
### 实施风险
|
||
|
||
- **开发周期风险**: 日志记录和查询功能开发周期可能较长
|
||
- **缓解措施**: 分阶段实施，优先实现核心功能，逐步完善
|
||
- **测试风险**: 日志记录和查询功能测试可能较为复杂
|
||
- **缓解措施**: 编写详细的测试用例，使用自动化测试，进行充分的测试
|
||
|
||
## 回滚策略
|
||
|
||
如果决策实施后出现问题，可以采取以下回滚策略：
|
||
|
||
1. **禁用日志记录功能**: 通过配置文件禁用日志记录功能，不影响作业执行
|
||
2. **回滚日志记录代码**: 回滚日志记录相关的代码，恢复到之前的版本
|
||
3. **回滚数据库表**: 删除日志记录相关的数据库表，恢复到之前的数据库结构
|
||
4. **回滚配置文件**: 回滚日志记录相关的配置文件，恢复到之前的配置
|
||
|
||
## 验收标准
|
||
|
||
定义验证该决策有效性的具体标准和测试方法：
|
||
|
||
1. **功能完整性**: 所有日志记录和查询功能能够正常工作
|
||
- 测试方法: 手动测试日志记录、日志查询、日志导出、日志分析
|
||
|
||
2. **性能指标**: 日志记录和查询性能满足要求，不影响作业执行
|
||
- 测试方法: 性能测试，监控日志记录和查询性能，确保不影响作业执行
|
||
|
||
3. **完整性**: 日志信息完整详细，能够追溯作业执行过程
|
||
- 测试方法: 手动测试日志记录，确保日志信息完整详细
|
||
|
||
4. **代码规范性**: 代码符合项目编码规范，有清晰的注释
|
||
- 测试方法: 代码审查，检查代码规范和注释
|
||
|
||
5. **可维护性**: 代码结构清晰，易于扩展和维护
|
||
- 测试方法: 代码审查，检查代码结构和可维护性
|
||
|
||
6. **可测试性**: 代码易于单元测试和集成测试
|
||
- 测试方法: 单元测试和集成测试，确保测试覆盖率高
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **快照时间**: 2026-01-19 00:00:00
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
||
|
||
- [REQ-010-15.md](../requirements/REQ-010-15.md) - 详细日志记录和查询需求文档
|
||
- [REQ-010.md](../requirements/REQ-010.md) - Salesforce元数据拉取和部署主需求文档
|
||
- [REQ-010-6.md](../requirements/REQ-010-6.md) - 元数据拉取核心功能需求文档
|
||
- [REQ-010-8.md](../requirements/REQ-010-8.md) - 元数据部署核心功能需求文档
|
||
- [REQ-010-14.md](../requirements/REQ-010-14.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 客户端参考文档（唯一真源）
|