datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0021-file-hash-comparison.md

架构决策记录 - 文件哈希对比和增量检测

背景

在 Salesforce 元数据拉取和部署过程中，每次都拉取或部署所有文件会导致性能低下，特别是在元数据文件数量较多的情况下。为了提高性能，需要实现文件哈希对比和增量检测功能，只拉取或部署变化的文件。

当前系统已经实现了文件存储和解压处理（REQ-010-7）和元数据组件索引和查询（REQ-010-11），需要在此基础上实现文件哈希对比和增量检测功能。

决策

1. 文件哈希计算方案

决策: 使用 Java MessageDigest 计算 SHA-256 哈希，使用流式处理大文件。

理由:

• SHA-256 是一种安全的哈希算法，能够准确识别文件变化
• Java MessageDigest 是 Java 标准库的一部分，无需额外依赖
• 流式处理可以避免一次性加载大文件到内存，降低内存使用

实现方案:

• 创建 IFileHashService 服务接口
• 创建 FileHashServiceImpl 服务实现
• 使用 MessageDigest.getInstance("SHA-256") 获取 SHA-256 哈希算法实例
• 使用 BufferedInputStream 流式读取文件，避免一次性加载大文件到内存
• 使用 8KB 缓冲区，平衡内存使用和读取性能

2. 哈希对比方案

决策: 使用哈希值直接对比，使用并行处理提高对比性能。

理由:

• 哈希值直接对比简单高效，能够准确识别文件变化
• 并行处理可以利用多核 CPU 的优势，提高对比性能
• 使用 Java 8 的 Stream API 可以方便地实现并行处理

实现方案:

• 创建 IHashComparisonService 服务接口
• 创建 HashComparisonServiceImpl 服务实现
• 使用 String.equals() 方法对比哈希值
• 使用 parallelStream() 并行处理多个文件
• 使用 ConcurrentHashMap 缓存哈希值，避免重复计算

3. 增量检测方案

决策: 使用哈希对比检测文件变化，使用文件系统监听器检测文件删除。

理由:

• 哈希对比能够准确识别文件的新增和修改
• 文件系统监听器能够实时检测文件删除
• 结合两种方式可以全面检测文件变化

实现方案:

• 创建 IIncrementalDetectionService 服务接口
• 创建 IncrementalDetectionServiceImpl 服务实现
• 使用哈希对比检测文件的新增和修改
• 使用 Java NIO 的 WatchService 监听文件系统事件
• 使用 ChangeType 枚举定义文件变化类型（ADDED、MODIFIED、DELETED）
• 使用 FileChange 实体类记录文件变化信息

4. 增量拉取方案

决策: 使用增量检测结果构建 package.xml，只拉取变化的文件。

理由:

• package.xml 是 Salesforce Metadata API 的标准配置格式，易于理解和维护
• 只拉取变化的文件可以减少网络传输和处理时间
• 复用现有的 IMetadataRetrieveService 服务接口，保持代码一致性

实现方案:

• 创建 IIncrementalRetrieveService 服务接口
• 创建 IncrementalRetrieveServiceImpl 服务实现
• 使用增量检测结果构建 package.xml
• 调用 IMetadataRetrieveService 的 retrieve() 方法，传入 package.xml
• 使用异步执行，避免阻塞主线程
• 复用现有的 AsyncConfig 配置类和线程池

5. 增量部署方案

决策: 使用增量检测结果构建 package.xml，只部署变化的文件。

理由:

• package.xml 是 Salesforce Metadata API 的标准配置格式，易于理解和维护
• 只部署变化的文件可以减少网络传输和处理时间
• 复用现有的 IMetadataDeployService 服务接口，保持代码一致性

实现方案:

• 创建 IIncrementalDeployService 服务接口
• 创建 IncrementalDeployServiceImpl 服务实现
• 使用增量检测结果构建 package.xml
• 调用 IMetadataDeployService 的 deploy() 方法，传入 package.xml
• 使用异步执行，避免阻塞主线程
• 复用现有的 AsyncConfig 配置类和线程池

备选方案

备选方案 1: 使用文件修改时间对比

优点:

• 实现简单，无需计算哈希值
• 性能较高，无需读取文件内容

缺点:

• 文件修改时间可能不准确，可能导致误判
• 无法检测文件内容是否真的发生变化

结论: 不采用，因为文件修改时间可能不准确，无法保证增量检测的准确性。

备选方案 2: 使用 MD5 哈希算法

优点:

• MD5 哈希计算速度快
• 实现简单

缺点:

• MD5 存在碰撞风险，安全性较低
• 不符合安全最佳实践

结论: 不采用，因为 MD5 存在碰撞风险，安全性较低，不符合安全最佳实践。

备选方案 3: 使用第三方库计算哈希

优点:

• 性能可能更高
• 功能可能更丰富

缺点:

• 增加依赖，增加项目复杂度
• 可能存在安全风险

结论: 不采用，因为 Java 标准库已经提供了足够的功能，无需额外依赖。

影响

对系统架构的影响

• 新增 file-hash 包，包含文件哈希对比和增量检测相关的服务、控制器、DTO、实体、Mapper、工具类
• 复用现有的 IFileStorageService 接口，用于读取文件内容
• 复用现有的 IMetadataRetrieveService 服务接口，用于增量拉取
• 复用现有的 IMetadataDeployService 服务接口，用于增量部署
• 复用现有的 AsyncConfig 配置类和线程池，用于异步执行

对开发流程的影响

• 开发人员需要了解文件哈希对比和增量检测的实现原理
• 需要编写单元测试和集成测试，确保功能正常
• 需要编写文档，说明如何使用文件哈希对比和增量检测功能

对运维管理的影响

• 需要监控文件哈希计算和对比的性能
• 需要监控增量拉取和部署的性能
• 需要定期清理过期的哈希值，避免占用过多存储空间

风险

技术风险

• 哈希计算风险: 哈希计算错误可能导致增量检测不准确
  • 缓解措施: 使用单元测试和集成测试验证哈希计算的准确性
• 对比性能风险: 对比性能不佳可能影响用户体验
  • 缓解措施: 使用并行处理提高对比性能，使用缓存避免重复计算
• 增量检测风险: 增量检测不准确可能导致遗漏或误判
  • 缓解措施: 使用哈希对比和文件系统监听器两种方式，全面检测文件变化

业务风险

• 增量拉取风险: 增量拉取失败可能导致文件不一致
  • 缓解措施: 提供回滚机制，支持重新拉取所有文件
• 增量部署风险: 增量部署失败可能导致部署不完整
  • 缓解措施: 提供回滚机制，支持重新部署所有文件

实施风险

• 性能风险: 文件哈希计算和对比性能可能不满足要求
  • 缓解措施: 使用流式处理和并行处理提高性能
• 兼容性风险: 新增功能可能与现有功能不兼容
  • 缓解措施: 充分测试，确保兼容性

回滚策略

如果决策实施后出现问题，可以采取以下回滚策略：

1. 禁用增量检测: 在配置中禁用增量检测功能，回退到全量拉取和部署
2. 重新计算哈希: 如果哈希计算出现问题，可以重新计算所有文件的哈希值
3. 回退到全量操作: 如果增量拉取或部署失败，可以回退到全量拉取和部署

验收标准

定义验证该决策有效性的具体标准和测试方法：

1. 功能完整性: 所有文件哈希对比和增量检测功能能够正常工作
2. 性能指标: 哈希计算和对比性能满足要求，增量拉取和部署性能满足要求
3. 准确性: 增量检测结果准确，只拉取或部署变化的文件
4. 代码规范性: 代码符合项目编码规范，有清晰的注释
5. 可维护性: 代码结构清晰，易于扩展和维护
6. 可测试性: 代码易于单元测试和集成测试

视觉锚点

Visual Reference

引用 Canvas 的具体节点或快照：

• Authentication.canvas - 相关架构图
• 具体节点: 集成核心 - 提供与Salesforce的各种连接方式

Status

• Draft
• Accepted
• Superceded

参考资料

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

• REQ-010-12.md - 文件哈希对比和增量检测需求文档
• REQ-010-7.md - 文件存储和解压处理需求文档
• REQ-010-11.md - 元数据组件索引和查询需求文档
• file/index.md - 文件模块 API 文档索引（唯一真源）