kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/sessions/20260118-metadata-api-client.md

9.7 KiB
Raw Blame History

执行会话记录 - Metadata API客户端封装

会话信息

  • 会话编号: Session-20260118-002
  • 创建日期: 2026-01-18
  • 相关需求: REQ-010-5 - Metadata API客户端封装
  • 相关决策: ADR-0014 - Metadata API客户端封装架构决策
  • 相关提示词: Prompt-015 - Metadata API客户端封装实现提示词

现状

当前系统已经完成了以下工作：

  1. 数据库表结构设计: 已完成 9 张表的设计和创建（REQ-010-1）
  2. 基础实体类和 Mapper 创建: 已完成基础实体类和 Mapper 的创建（REQ-010-2）
  3. Salesforce 组织配置管理: 已完成组织配置管理的实现（REQ-010-3）
  4. 元数据任务定义管理: 已完成任务定义管理的实现（REQ-010-4）
  5. Metadata API 客户端封装需求: 已完成需求文档的编写（REQ-010-5）
  6. 架构决策: 已完成 Metadata API 客户端封装的架构决策（ADR-0014）
  7. 提示词资产化: 已完成 Metadata API 客户端封装的提示词编写（Prompt-015）

目标

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

执行过程

步骤1：创建 MetadataApiClient 客户端类

操作

创建 MetadataApiClient 客户端类，封装 Salesforce Metadata API 调用，包含以下方法：

  • getMetadataConnection: 获取 Metadata 连接
  • retrieve: 检索元数据
  • deploy: 部署元数据
  • checkRetrieveStatus: 检查检索状态
  • checkDeployStatus: 检查部署状态

结果

MetadataApiClient 客户端类创建成功，使用 Salesforce WSC 库，与 SessionManager 集成成功。

步骤2：创建 MetadataApiService 服务层

操作

创建 IMetadataApiService 接口和 MetadataApiServiceImpl 实现类，实现以下方法：

  • retrieveAsync: 异步检索元数据
  • deployAsync: 异步部署元数据
  • cancelJob: 取消任务
  • getJobStatus: 获取任务状态

结果

Service 层创建成功，使用 @Service 注解进行标注，使用 @Async 注解实现异步执行，使用 CompletableFuture 返回异步结果。

步骤3：创建 AsyncConfig 配置类

操作

创建 AsyncConfig 配置类，配置线程池，包含以下配置：

  • 核心线程数: 5
  • 最大线程数: 10
  • 队列容量: 100
  • 线程名称前缀: metadata-task-
  • 拒绝策略: CallerRunsPolicy

结果

AsyncConfig 配置类创建成功，使用 @Configuration 和 @EnableAsync 注解进行标注，使用 ThreadPoolTaskExecutor 配置线程池。

步骤4：创建状态轮询机制

操作

创建 MetadataPollingTask 轮询任务，实现以下功能：

  • 定时轮询任务状态
  • 支持超时处理
  • 支持取消轮询
  • 更新任务状态

结果

状态轮询机制创建成功，使用 @Scheduled 注解创建定时任务，使用 ConcurrentHashMap 存储轮询任务状态。

步骤5：创建 Zip 文件处理工具类

操作

创建 ZipUtil 工具类，实现以下方法：

  • unzip: 解压 Zip 文件
  • readZipFile: 读取 Zip 文件内容

结果

ZipUtil 工具类创建成功，使用 ZipInputStream 处理 Zip 文件，使用流式处理避免内存溢出。

步骤6：创建 MetadataApiUtil 工具类

操作

创建 MetadataApiUtil 工具类，实现以下方法：

  • parsePackageXml: 解析 package.xml
  • parseDeployResult: 解析部署结果
  • extractErrorMessages: 提取错误信息
  • extractCodeCoverage: 提取代码覆盖率

结果

MetadataApiUtil 工具类创建成功，使用 XML 解析库解析 package.xml，使用 JSON 解析库处理 API 响应。

步骤7：创建自定义异常类

操作

创建 MetadataApiException 异常类，继承自 RuntimeException，包含以下属性：

  • errorCode: 错误代码
  • errorMessage: 错误信息
  • cause: 原因

结果

自定义异常类创建成功，使用统一的异常处理机制。

步骤8：创建结果类

操作

创建以下结果类：

  • RetrieveResult: 检索结果类
  • DeployResult: 部署结果类
  • JobStatus: 任务状态类

结果

结果类创建成功，包含任务ID、状态、错误信息等属性。

步骤9：创建 Controller 层

操作

创建 MetadataApiController 控制器，实现以下接口：

  • POST /metadata/retrieve - 检索元数据
  • POST /metadata/deploy - 部署元数据
  • GET /metadata/job/{jobId}/status - 获取任务状态
  • DELETE /metadata/job/{jobId} - 取消任务

结果

Controller 层创建成功，使用 @RestController 和 @RequestMapping 注解进行标注。

步骤10：创建前端组件

操作

创建 MetadataManager.vue 前端组件，实现以下功能：

  • 元数据检索界面
  • 元数据部署界面
  • 任务状态查询界面
  • 任务取消界面

结果

前端组件创建成功，使用 Vue 3 和 Element Plus 进行开发。

AI 质疑和替代方案

质疑1：为什么使用 Spring 的 @Async 注解而不是消息队列？

AI 质疑: 为什么选择使用 Spring 的 @Async 注解实现异步执行，而不是使用消息队列（如 RabbitMQ、Kafka）？

回答: 根据 ADR-0014 的决策，选择使用 Spring 的 @Async 注解是因为：

  1. Spring 的 @Async 注解简单易用，无需额外配置
  2. Spring 提供了线程池管理，可以控制并发数和资源使用
  3. 异步执行不影响系统响应，提高用户体验
  4. 支持异步任务的状态跟踪和结果获取
  5. 对于简单的异步任务，使用消息队列是过度设计

替代方案: 如果未来需要更复杂的异步任务管理，可以考虑使用消息队列。

质疑2：为什么使用定时任务实现状态轮询而不是回调机制？

AI 质疑: 为什么选择使用定时任务实现状态轮询，而不是使用回调机制？

回答: 选择使用定时任务实现状态轮询是因为：

  1. Salesforce Metadata API 不支持回调机制
  2. 定时任务简单易用，无需额外引入其他库
  3. 可以控制轮询频率，避免 API 限流
  4. 支持超时处理，防止无限轮询
  5. 支持取消轮询，提高灵活性

替代方案: 如果 Salesforce Metadata API 未来支持回调机制，可以考虑使用回调机制。

质疑3：为什么使用 ZipInputStream 而不是其他 Zip 库？

AI 质疑: 为什么选择使用 Java 的 ZipInputStream 处理 Zip 文件，而不是使用其他 Zip 库（如 Apache Commons Compress）？

回答: 选择使用 Java 的 ZipInputStream 是因为：

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

替代方案: 如果需要更复杂的 Zip 文件处理功能，可以考虑使用 Apache Commons Compress。

最终复现步骤

1. 创建 MetadataApiClient 客户端类

创建 MetadataApiClient.java 客户端类。

2. 创建 MetadataApiService 服务层

创建 IMetadataApiService.java 接口和 MetadataApiServiceImpl.java 实现类。

3. 创建 AsyncConfig 配置类

创建 AsyncConfig.java 配置类。

4. 创建状态轮询机制

创建 MetadataPollingTask.java 轮询任务。

5. 创建 Zip 文件处理工具类

创建 ZipUtil.java 工具类。

6. 创建 MetadataApiUtil 工具类

创建 MetadataApiUtil.java 工具类。

7. 创建自定义异常类

创建 MetadataApiException.java 异常类。

8. 创建结果类

创建 RetrieveResult.java、DeployResult.java、JobStatus.java 结果类。

9. 创建 Controller 层

创建 MetadataApiController.java 控制器。

10. 创建前端组件

创建 MetadataManager.vue 前端组件。

11. 编写单元测试

为以下类编写单元测试：

  • MetadataApiClient
  • MetadataApiServiceImpl
  • ZipUtil
  • MetadataApiUtil

12. 编写集成测试

编写以下集成测试：

  • Metadata API 客户端调用测试
  • 异步执行测试
  • 状态轮询测试
  • Zip 文件处理测试
  • 错误处理测试

13. 编写 API 文档

为以下接口编写 API 文档：

  • POST /metadata/retrieve - 检索元数据
  • POST /metadata/deploy - 部署元数据
  • GET /metadata/job/{jobId}/status - 获取任务状态
  • DELETE /metadata/job/{jobId} - 取消任务

执行结果

成功实现的功能

  1. ✅ MetadataApiClient 客户端类创建成功
  2. ✅ MetadataApiService 服务层创建成功
  3. ✅ AsyncConfig 配置类创建成功
  4. ✅ 状态轮询机制创建成功
  5. ✅ Zip 文件处理工具类创建成功
  6. ✅ MetadataApiUtil 工具类创建成功
  7. ✅ 自定义异常类创建成功
  8. ✅ 结果类创建成功
  9. ✅ Controller 层创建成功
  10. ✅ 前端组件创建成功

未实现的功能

无

遇到的问题

无

相关文档

审核记录

日期 审核人 审核结果 审核意见
2026-01-18 Datai Team 已通过 实现完整，符合需求

变更历史

日期 版本 变更内容 变更人
2026-01-18 v1.0.0 初始版本 Datai Team