14 KiB
架构决策记录 - Metadata API客户端封装
背景
REQ-010-5 需要封装 Salesforce Metadata API 客户端，提供 retrieve() 和 deploy() 方法的调用接口，支持异步执行、状态轮询、Job ID 获取、Zip 文件下载、部署结果解析、错误处理机制等。
当前项目已经完成了数据库表结构设计、基础实体类和 Mapper 创建、Salesforce 组织配置管理、元数据任务定义管理等功能，现在需要实现 Metadata API 客户端封装，为后续的元数据拉取和部署功能提供基础。
决策
1. MetadataApiClient 客户端类创建方案
决策: 使用 Salesforce WSC (Web Service Connector) 库创建 MetadataApiClient 客户端类，封装 Salesforce Metadata API 调用。
理由:
- Salesforce WSC 库是官方推荐的 Java 客户端库，提供了完整的 Metadata API 支持
- WSC 库已经处理了 SOAP 协议的复杂性，简化了 API 调用
- WSC 库支持异步调用和状态轮询，满足业务需求
- WSC 库支持 OAuth 认证，与 SessionManager 集成方便
实现方案:
- 使用 Salesforce WSC 库创建 MetadataApiClient 客户端类
- 使用 SessionManager 进行会话管理和自动重新登录
- 使用 WSC 库的 MetadataConnection 类创建连接
- 使用 WSC 库的 RetrieveRequest 和 DeployRequest 类创建请求
- 使用 WSC 库的 AsyncResult 类处理异步结果
2. retrieve() 方法实现方案
决策: 使用异步线程池执行 retrieve() 方法，使用轮询机制检查任务状态，使用 ZipInputStream 处理 Zip 文件。
理由:
- 异步线程池可以避免阻塞主线程，提高系统响应速度
- 轮询机制可以及时获取任务状态，支持超时处理
- ZipInputStream 可以流式处理 Zip 文件，避免内存溢出
- 支持大文件处理，满足业务需求
实现方案:
- 使用 Spring 的 @Async 注解实现异步执行
- 使用 ThreadPoolTaskExecutor 配置线程池
- 使用 WSC 库的 checkStatus() 方法检查任务状态
- 使用 ScheduledExecutorService 实现轮询机制
- 使用 ZipInputStream 处理 Zip 文件，使用流式处理避免内存溢出
3. deploy() 方法实现方案
决策: 使用异步线程池执行 deploy() 方法，使用轮询机制检查任务状态，使用 JSON 解析库处理 API 响应。
理由:
- 异步线程池可以避免阻塞主线程，提高系统响应速度
- 轮询机制可以及时获取任务状态，支持超时处理
- JSON 解析库可以灵活处理 API 响应，提取错误信息和代码覆盖率
- 支持多种部署状态，满足业务需求
实现方案:
- 使用 Spring 的 @Async 注解实现异步执行
- 使用 ThreadPoolTaskExecutor 配置线程池
- 使用 WSC 库的 checkStatus() 方法检查任务状态
- 使用 ScheduledExecutorService 实现轮询机制
- 使用 Jackson 库处理 API 响应，使用正则表达式提取错误信息
4. 状态轮询机制方案
决策: 使用定时任务实现轮询机制，使用超时机制防止无限轮询，使用取消机制支持取消轮询。
理由:
- 定时任务可以定期检查任务状态，及时获取任务进度
- 超时机制可以防止无限轮询，避免资源浪费
- 取消机制可以支持用户取消任务，提高用户体验
- 轮询频率合理，避免 API 限流
实现方案:
- 使用 ScheduledExecutorService 实现定时任务
- 使用 Future 接口支持取消操作
- 使用 TimeoutException 处理超时情况
- 使用指数退避算法调整轮询频率，避免 API 限流
5. Zip 文件处理方案
决策: 使用 ZipInputStream 处理 Zip 文件，使用流式处理避免内存溢出，支持大文件处理。
理由:
- ZipInputStream 是 Java 标准库的一部分，无需引入额外依赖
- ZipInputStream 支持流式处理，可以逐个文件处理，避免内存溢出
- 支持大文件处理，满足业务需求
- 内存使用合理，不会因为文件过大导致内存溢出
实现方案:
- 使用 ZipInputStream 处理 Zip 文件
- 使用 BufferedInputStream 提高读取性能
- 使用 ByteArrayOutputStream 临时存储文件内容
- 使用 FileOutputStream 保存文件到磁盘
6. 部署结果解析方案
决策: 使用 Jackson 库处理 API 响应，使用正则表达式提取错误信息和代码覆盖率。
理由:
- Jackson 库是 Java 标准的 JSON 解析库，性能高，功能强大
- 正则表达式可以灵活提取错误信息和代码覆盖率
- 支持多种部署状态，满足业务需求
- 错误信息详细，方便用户排查问题
实现方案:
- 使用 Jackson 库的 ObjectMapper 类处理 API 响应
- 使用 JsonNode 类遍历 JSON 数据
- 使用 Pattern 和 Matcher 类提取错误信息和代码覆盖率
- 使用自定义异常类处理部署错误
7. 错误处理机制方案
决策: 使用统一的异常处理机制，使用重试机制处理网络异常，使用日志记录机制记录错误信息。
理由:
- 统一的异常处理机制可以简化代码，提高代码质量
- 重试机制可以处理网络异常，提高系统稳定性
- 日志记录机制可以记录错误信息，方便排查问题
- 支持多种异常类型，满足业务需求
实现方案:
- 使用自定义异常类封装 API 调用异常
- 使用 @Retryable 注解实现重试机制
- 使用 Slf4j 记录错误信息
- 使用 GlobalExceptionHandler 统一处理异常
备选方案
1. MetadataApiClient 客户端类创建备选方案
备选方案 1: 使用 Salesforce REST API 创建 MetadataApiClient 客户端类
优点:
- REST API 是轻量级的，易于使用
- 不需要引入额外的依赖
缺点:
- REST API 功能有限，不支持所有 Metadata API 功能
- 需要手动处理 SOAP 协议，开发成本高
- 不支持异步调用和状态轮询
备选方案 2: 使用第三方库创建 MetadataApiClient 客户端类
优点:
- 第三方库可能提供更友好的 API
- 可能提供额外的功能
缺点:
- 第三方库可能不稳定，维护成本高
- 第三方库可能不支持所有 Metadata API 功能
- 第三方库可能不兼容 WSC 库
2. retrieve() 方法实现备选方案
备选方案 1: 使用同步方式实现 retrieve() 方法
优点:
- 实现简单，不需要处理异步逻辑
- 代码易于理解和维护
缺点:
- 同步方式会阻塞主线程，影响系统响应速度
- 不支持超时处理和取消操作
备选方案 2: 使用消息队列实现 retrieve() 方法
优点:
- 消息队列可以解耦任务提交和任务执行
- 支持任务持久化和重试
缺点:
- 消息队列增加了系统复杂度
- 需要引入额外的依赖
3. deploy() 方法实现备选方案
备选方案 1: 使用同步方式实现 deploy() 方法
优点:
- 实现简单，不需要处理异步逻辑
- 代码易于理解和维护
缺点:
- 同步方式会阻塞主线程，影响系统响应速度
- 不支持超时处理和取消操作
备选方案 2: 使用消息队列实现 deploy() 方法
优点:
- 消息队列可以解耦任务提交和任务执行
- 支持任务持久化和重试
缺点:
- 消息队列增加了系统复杂度
- 需要引入额外的依赖
4. 状态轮询机制备选方案
备选方案 1: 使用回调机制实现状态轮询
优点:
- 回调机制可以及时获取任务状态
- 不需要定时任务，实现简单
缺点:
- Salesforce Metadata API 不支持回调机制
- 需要使用 Webhook，增加系统复杂度
备选方案 2: 使用 WebSocket 实现状态轮询
优点:
- WebSocket 可以实时推送任务状态
- 用户体验好
缺点:
- WebSocket 增加了系统复杂度
- 需要引入额外的依赖
5. Zip 文件处理备选方案
备选方案 1: 使用 ZipFile 类处理 Zip 文件
优点:
- ZipFile 类提供了随机访问功能
- 可以直接读取 Zip 文件中的文件
缺点:
- ZipFile 类需要将整个 Zip 文件加载到内存，可能导致内存溢出
- 不支持大文件处理
备选方案 2: 使用第三方库处理 Zip 文件
优点:
- 第三方库可能提供更好的性能
- 可能提供额外的功能
缺点:
- 第三方库增加了依赖
- 可能不稳定
6. 部署结果解析备选方案
备选方案 1: 使用 XML 解析库处理 API 响应
优点:
- XML 解析库可以处理 XML 格式的 API 响应
缺点:
- XML 解析库增加了依赖
- XML 解析比 JSON 解析慢
备选方案 2: 使用字符串处理提取错误信息和代码覆盖率
优点:
- 字符串处理不需要引入额外的依赖
- 实现简单
缺点:
- 字符串处理容易出错，维护成本高
- 不支持复杂的提取逻辑
7. 错误处理机制备选方案
备选方案 1: 使用 try-catch 处理异常
优点:
- try-catch 是 Java 标准的异常处理机制
- 实现简单
缺点:
- try-catch 需要在每个方法中重复编写，代码冗余
- 不支持重试机制
备选方案 2: 使用 AOP 实现异常处理
优点:
- AOP 可以统一处理异常，减少代码冗余
- 支持切面编程，灵活度高
缺点:
- AOP 增加了系统复杂度
- 需要引入额外的依赖
影响
系统架构影响
- 新增 MetadataApiClient 客户端类，封装 Salesforce Metadata API 调用
- 新增异步线程池，支持异步执行
- 新增状态轮询机制，支持任务状态查询
- 新增 Zip 文件处理功能，支持大文件处理
- 新增部署结果解析功能，支持错误信息和代码覆盖率提取
- 新增错误处理机制，支持异常处理和重试
开发流程影响
- 需要引入 Salesforce WSC 库依赖
- 需要配置异步线程池
- 需要编写单元测试和集成测试
- 需要编写使用文档
运维管理影响
- 需要监控异步线程池的使用情况
- 需要监控状态轮询的频率
- 需要监控 Zip 文件处理的性能
- 需要监控 API 调用的成功率
风险
技术风险
- WSC 库版本兼容性风险: WSC 库版本可能与项目其他依赖不兼容
- 异步执行风险: 异步执行机制复杂可能导致状态管理困难
- 状态轮询风险: 状态轮询频率不当可能导致 API 限流
- Zip 文件处理风险: Zip 文件处理不当可能导致内存溢出
- 错误处理风险: 错误处理不完善可能导致任务失败无法恢复
业务风险
- API 调用失败风险: API 调用失败可能导致元数据拉取和部署失败
- 任务状态不一致风险: 任务状态不一致可能导致用户困惑
- 数据丢失风险: Zip 文件处理失败可能导致数据丢失
- 部署失败风险: 部署失败可能导致系统不可用
实施风险
- 开发时间风险: 开发时间可能超出预期
- 测试时间风险: 测试时间可能超出预期
- 上线时间风险: 上线时间可能超出预期
回滚策略
如果决策实施后出现问题，可以采取以下回滚策略：
- 回滚 WSC 库版本: 如果 WSC 库版本兼容性问题，可以回滚到之前的版本
- 禁用异步执行: 如果异步执行机制有问题，可以禁用异步执行，使用同步方式
- 调整轮询频率: 如果状态轮询频率有问题，可以调整轮询频率
- 禁用 Zip 文件处理: 如果 Zip 文件处理有问题，可以禁用 Zip 文件处理，使用其他方式
- 简化错误处理: 如果错误处理机制有问题，可以简化错误处理，使用 try-catch
验收标准
定义验证该决策有效性的具体标准和测试方法：
-
MetadataApiClient 客户端类创建验收标准:
- MetadataApiClient 创建成功
- 使用 Salesforce WSC 库成功
- 与 SessionManager 集成成功
- 代码符合项目编码规范
-
retrieve() 方法实现验收标准:
- retrieve() 方法调用成功
- 支持异步执行
- 支持 Job ID 获取
- 支持状态轮询
- 支持 Zip 文件下载
- 错误处理机制正常工作
-
deploy() 方法实现验收标准:
- deploy() 方法调用成功
- 支持异步执行
- 支持 Job ID 获取
- 支持状态轮询
- 支持部署结果解析
- 错误处理机制正常工作
-
状态轮询机制验收标准:
- 状态轮询机制正常工作
- 轮询频率合理
- 支持超时处理
- 支持取消轮询
-
Zip 文件处理验收标准:
- Zip 文件下载成功
- Zip 文件解压成功
- 支持大文件处理
- 内存使用合理
-
部署结果解析验收标准:
- 部署结果解析成功
- 错误信息提取正确
- 代码覆盖率提取正确
- 支持多种部署状态
-
错误处理机制验收标准:
- 错误处理机制正常工作
- 支持多种异常类型
- 错误信息详细
- 支持错误重试
视觉锚点
Visual Reference
引用 Canvas 的具体节点或快照：
- Authentication.canvas - 项目架构视觉化展示
- 相关节点: 集成核心 - 提供与Salesforce的各种连接方式
- 相关节点: SessionManager - 会话管理，提供登录服务
Status
- Draft
- Accepted
- Superceded
参考资料
列出与该决策相关的参考资料，包括文档、文章或其他资源：
- REQ-010-5.md - Metadata API客户端封装需求文档
- REQ-010-1.md - 数据库表结构设计和创建
- REQ-010-2.md - 基础实体类和Mapper创建
- REQ-010-3.md - Salesforce组织配置管理
- REQ-010-4.md - 元数据任务定义管理
- Salesforce Metadata API Developer Guide - Salesforce Metadata API 官方文档
- Salesforce WSC (Web Service Connector) - Salesforce WSC 库 GitHub 仓库
- Spring Async Documentation - Spring 异步支持文档