kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3dde4fb6d7
datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0014-metadata-api-client.md
Kris 2e6f087732 docs: 完成REQ-010-17和REQ-010-2的文档创建 
- 完成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方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
2026-01-19 10:06:09 +08:00

11 KiB
Raw Blame History

架构决策记录 (ADR) - Metadata API客户端封装

背景

REQ-010-5 需要封装 Salesforce Metadata API 客户端，提供 retrieve() 和 deploy() 方法的调用接口，支持异步执行和状态轮询。当前系统已经完成了以下工作：

  1. 数据库表结构设计和创建 (REQ-010-1): 已完成 9 张表的设计和创建
  2. 基础实体类和 Mapper 创建 (REQ-010-2): 已完成基础实体类和 Mapper 的创建
  3. Salesforce 组织配置管理 (REQ-010-3): 已完成组织配置管理的实现
  4. 元数据任务定义管理 (REQ-010-4): 已完成任务定义管理的实现

现在需要封装 Salesforce Metadata API 客户端，提供 retrieve() 和 deploy() 方法的调用接口，支持异步执行和状态轮询。

决策

1. 客户端封装方案

决策: 使用 Salesforce WSC (Web Service Connector) 库封装 Metadata API 客户端，创建 MetadataApiClient 类。

理由:

  • Salesforce WSC 是官方推荐的 Java 客户端库，与 Metadata API 兼容性最好
  • WSC 库已经包含了所有 Metadata API 的类型定义，无需额外定义
  • WSC 库支持异步操作和状态轮询，符合需求要求
  • 项目已经引入了 WSC 库依赖，无需额外引入其他库

实现方案:

  • 创建 MetadataApiClient 类，封装 MetadataConnection
  • 使用 SessionManager 进行会话管理和自动重新登录
  • 提供 retrieve() 和 deploy() 方法，支持异步执行
  • 提供状态轮询方法，检查任务执行状态
  • 提供 Zip 文件下载和解压方法
  • 提供部署结果解析方法
  • 提供统一的错误处理机制

2. 异步执行方案

决策: 使用 Spring 的 @Async 注解和线程池实现异步执行。

理由:

  • Spring 的 @Async 注解简单易用，无需额外配置
  • Spring 提供了线程池管理，可以控制并发数和资源使用
  • 异步执行不影响系统响应，提高用户体验
  • 支持异步任务的状态跟踪和结果获取

实现方案:

  • 创建 AsyncConfig 配置类，配置线程池
  • 使用 @Async 注解标记异步方法
  • 使用 CompletableFuture 返回异步结果
  • 使用 ConcurrentHashMap 存储异步任务状态
  • 提供任务取消和超时处理

3. 状态轮询方案

决策: 使用定时任务实现状态轮询，使用超时机制防止无限轮询。

理由:

  • 定时任务简单易用，无需额外引入其他库
  • 可以控制轮询频率，避免 API 限流
  • 支持超时处理，防止无限轮询
  • 支持取消轮询，提高灵活性

实现方案:

  • 使用 @Scheduled 注解创建定时任务
  • 使用 ConcurrentHashMap 存储轮询任务状态
  • 设置合理的轮询频率（如每 5 秒轮询一次）
  • 设置超时时间（如 30 分钟）
  • 提供取消轮询的方法

4. Zip 文件处理方案

决策: 使用 ZipInputStream 处理 Zip 文件，使用流式处理避免内存溢出。

理由:

  • Java 的 ZipInputStream 是标准库，无需额外引入其他库
  • 流式处理可以避免内存溢出，支持大文件处理
  • 可以逐条读取 Zip 文件中的条目，提高处理效率
  • 支持解压到指定目录，便于后续处理

实现方案:

  • 使用 ZipInputStream 读取 Zip 文件
  • 使用 FileOutputStream 写入解压后的文件
  • 使用流式处理，避免一次性加载整个 Zip 文件
  • 提供进度跟踪，支持大文件处理
  • 提供错误处理，处理损坏的 Zip 文件

5. 错误处理方案

决策: 使用统一的异常处理机制，使用重试机制处理网络异常。

理由:

  • 统一的异常处理机制可以提高代码可维护性
  • 重试机制可以处理网络异常等临时性错误
  • 详细的错误信息可以帮助问题排查
  • 支持多种异常类型，提高系统健壮性

实现方案:

  • 创建自定义异常类，如 MetadataApiException
  • 使用 @ControllerAdvice 统一处理异常
  • 使用 @Retryable 注解实现重试机制
  • 记录详细的错误日志
  • 提供友好的错误信息返回

备选方案

备选方案1: 使用 Apache HttpClient 封装 Metadata API

描述: 使用 Apache HttpClient 直接调用 Metadata API 的 REST 端点。

优点:

  • 更加灵活，可以自定义请求和响应处理
  • 可以更好地控制请求超时和重试策略
  • 不依赖 WSC 库，减少依赖

缺点:

  • 需要手动处理 Metadata API 的类型定义
  • 需要手动处理 SOAP 消息的序列化和反序列化
  • 开发复杂度高，容易出错
  • 与官方文档不一致，维护成本高

结论: 不采用，开发复杂度高，维护成本高。

备选方案2: 使用第三方库如 Force.com Toolkit

描述: 使用第三方库如 Force.com Toolkit for Java。

优点:

  • 提供了更高级的抽象，简化了 API 调用
  • 提供了更多功能，如批量操作、查询等
  • 社区活跃，文档完善

缺点:

  • 需要额外引入第三方库
  • 可能与项目现有的技术栈不兼容
  • 可能不支持最新的 Metadata API 功能
  • 增加了项目的依赖复杂度

结论: 不采用，增加了项目的依赖复杂度，与项目现有的技术栈不兼容。

备选方案3: 使用消息队列实现异步执行

描述: 使用消息队列（如 RabbitMQ、Kafka）实现异步执行。

优点:

  • 可以更好地控制并发数和资源使用
  • 支持任务持久化，避免任务丢失
  • 支持任务优先级和调度
  • 可以分布式部署，提高可扩展性

缺点:

  • 需要额外引入消息队列，增加了系统复杂度
  • 需要额外的运维成本
  • 对于简单的异步任务，过度设计
  • 增加了项目的依赖复杂度

结论: 不采用，对于简单的异步任务，过度设计，增加了系统复杂度。

影响

对系统架构的影响

  1. 新增模块: 在 datai-salesforce-metadata 模块下新增 MetadataApiClient 类
  2. 依赖关系: 依赖于 SessionManager 进行会话管理和自动重新登录
  3. 异步执行: 使用 Spring 的 @Async 注解和线程池实现异步执行
  4. 状态轮询: 使用定时任务实现状态轮询

对开发流程的影响

  1. 开发复杂度: 需要理解 Salesforce Metadata API 的调用规范
  2. 测试复杂度: 需要模拟 Metadata API 的响应，测试复杂度高
  3. 文档需求: 需要编写详细的 API 文档和使用示例

对运维管理的影响

  1. 监控需求: 需要监控异步任务的执行状态和性能
  2. 日志需求: 需要记录详细的日志，便于问题排查
  3. 配置需求: 需要配置线程池参数和轮询参数

风险

技术风险

  1. WSC 库版本风险: WSC 库版本兼容性问题，可能不支持最新的 Metadata API 功能

    • 缓解措施: 选择稳定的 WSC 库版本，定期更新

  2. 异步执行风险: 异步执行机制复杂可能导致状态管理困难

    • 缓解措施: 使用 ConcurrentHashMap 存储异步任务状态，提供任务取消和超时处理

  3. 状态轮询风险: 状态轮询频率不当可能导致 API 限流

    • 缓解措施: 设置合理的轮询频率（如每 5 秒轮询一次），使用超时机制防止无限轮询

  4. Zip 文件处理风险: Zip 文件处理不当可能导致内存溢出

    • 缓解措施: 使用流式处理，避免一次性加载整个 Zip 文件，支持大文件处理

  5. 错误处理风险: 错误处理不完善可能导致任务失败无法恢复

    • 缓解措施: 使用统一的异常处理机制，使用重试机制处理网络异常

业务风险

  1. API 限流风险: Metadata API 有调用次数限制，可能导致任务失败

    • 缓解措施: 实现请求限流机制，避免短时间内大量请求

  2. 数据一致性风险: 异步执行可能导致数据不一致

    • 缓解措施: 使用事务机制，确保数据一致性

实施风险

  1. 开发周期风险: 开发复杂度高，可能延长开发周期

    • 缓解措施: 分阶段实施，先实现核心功能，再实现辅助功能

  2. 测试风险: 测试复杂度高，可能遗漏边界情况

    • 缓解措施: 编写详细的测试用例，覆盖各种边界情况

回滚策略

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

  1. 回滚代码: 删除 MetadataApiClient 类和相关代码
  2. 回滚配置: 删除 AsyncConfig 配置类和相关配置
  3. 回滚数据库: 删除相关的数据库表（如果有的话）
  4. 回滚文档: 删除相关的文档和记录

回滚后，可以考虑以下替代方案：

  • 使用 Apache HttpClient 封装 Metadata API
  • 使用第三方库如 Force.com Toolkit
  • 使用消息队列实现异步执行

验收标准

功能验收标准

  1. MetadataApiClient 创建成功: MetadataApiClient 类创建成功，使用 Salesforce WSC 库
  2. retrieve() 方法实现成功: retrieve() 方法调用成功，支持异步执行、Job ID 获取、状态轮询、Zip 文件下载
  3. deploy() 方法实现成功: deploy() 方法调用成功，支持异步执行、Job ID 获取、状态轮询、部署结果解析
  4. 状态轮询机制正常工作: 状态轮询机制正常工作，轮询频率合理，支持超时处理和取消轮询
  5. Zip 文件处理正常工作: Zip 文件下载成功，解压成功，支持大文件处理，内存使用合理
  6. 部署结果解析正常工作: 部署结果解析成功，错误信息提取正确，代码覆盖率提取正确，支持多种部署状态
  7. 错误处理机制正常工作: 错误处理机制正常工作，支持多种异常类型，错误信息详细，支持错误重试

性能验收标准

  1. 异步执行不影响系统响应: 异步执行不影响系统响应，系统响应时间在可接受范围内
  2. 轮询频率合理: 轮询频率合理，不会导致 API 限流
  3. 内存使用合理: Zip 文件处理时内存使用合理，不会导致内存溢出

代码质量验收标准

  1. 代码符合项目编码规范: 代码符合项目编码规范，有清晰的注释
  2. 代码结构清晰: 代码结构清晰，易于扩展和维护
  3. 代码易于测试: 代码易于单元测试和集成测试

视觉锚点

Visual Reference

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

Status

  • Draft
  • Accepted
  • Superceded

参考资料

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

  1. REQ-010-5.md - Metadata API客户端封装需求
  2. metadata-module.md - Salesforce Metadata API 模块说明
  3. index.md - Salesforce SOAP API Java 客户端参考文档
  4. Salesforce Metadata API 开发者指南
  5. Salesforce WSC (Web Service Connector) 文档
  6. Spring @Async 文档
  7. Spring @Scheduled 文档