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方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
277 lines
11 KiB
Markdown
277 lines
11 KiB
Markdown
# 架构决策记录 (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 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与 Salesforce 的各种连接方式
|
||
- **具体节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
||
|
||
1. [REQ-010-5.md](../requirements/REQ-010-5.md) - Metadata API客户端封装需求
|
||
2. [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明
|
||
3. [index.md](../reference-code/com/docs/index.md) - Salesforce SOAP API Java 客户端参考文档
|
||
4. [Salesforce Metadata API 开发者指南](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/)
|
||
5. [Salesforce WSC (Web Service Connector) 文档](https://github.com/forcedotcom/wsc)
|
||
6. [Spring @Async 文档](https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#scheduling-annotation-support-async)
|
||
7. [Spring @Scheduled 文档](https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#scheduling-annotation-support-scheduled)
|