kris/datai

Fork 0

Kris 3d290a8dd1 feat：归档当前所有文件

2026-01-28 18:23:25 +08:00

11 KiB

Raw Permalink Blame History

变更记录 - Metadata API客户端封装

变更信息

变更编号: Change-015
变更日期: 2026-01-18
变更类型: 新增功能
变更版本: 0.1.17
相关需求: REQ-010-5 - Metadata API客户端封装
相关决策: ADR-0014 - Metadata API客户端封装架构决策
相关会话: Session-20260118-002 - Metadata API客户端封装执行会话

变更摘要

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

变更详情

新增功能

1. MetadataApiClient 客户端类

描述: 创建 MetadataApiClient 客户端类，封装 Salesforce Metadata API 调用。

实现内容:

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

技术实现:

使用 Salesforce WSC (Web Service Connector) 库
使用 SessionManager 进行会话管理和自动重新登录
使用 ConnectorConfig 配置连接参数
使用 MetadataConnection 调用 Metadata API

2. MetadataApiService 服务层

描述: 创建 MetadataApiService 服务层，提供异步检索和部署接口。

实现内容:

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

技术实现:

使用 @Service 注解标注服务类
使用 @Async 注解实现异步执行
使用 CompletableFuture 返回异步结果
使用 ConcurrentHashMap 存储异步任务状态

3. AsyncConfig 配置类

描述: 创建 AsyncConfig 配置类，配置线程池。

实现内容:

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

技术实现:

使用 @Configuration 注解标注配置类
使用 @EnableAsync 注解启用异步支持
使用 ThreadPoolTaskExecutor 配置线程池

4. 状态轮询机制

描述: 创建状态轮询机制，使用定时任务轮询任务状态。

实现内容:

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

技术实现:

使用 @Scheduled 注解创建定时任务
使用 ConcurrentHashMap 存储轮询任务状态
设置轮询频率: 每 5 秒轮询一次
设置超时时间: 30 分钟

5. Zip 文件处理工具类

描述: 创建 ZipUtil 工具类，处理 Zip 文件。

实现内容:

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

技术实现:

使用 ZipInputStream 处理 Zip 文件
使用 FileOutputStream 写入解压后的文件
使用流式处理避免内存溢出
支持大文件处理

6. MetadataApiUtil 工具类

描述: 创建 MetadataApiUtil 工具类，提供 Metadata API 工具方法。

实现内容:

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

技术实现:

使用 XML 解析库解析 package.xml
使用 JSON 解析库处理 API 响应
使用正则表达式提取错误信息
使用正则表达式提取代码覆盖率

7. 自定义异常类

描述: 创建 MetadataApiException 异常类，提供统一的异常处理机制。

实现内容:

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

技术实现:

继承自 RuntimeException
提供多个构造函数
支持错误代码和错误信息

8. 结果类

描述: 创建结果类，封装任务执行结果。

实现内容:

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

技术实现:

使用 Lombok 的 @Data 注解
包含任务ID、状态、错误信息等属性
提供友好的状态枚举

9. MetadataApiController 控制器

描述: 创建 MetadataApiController 控制器，提供 RESTful API 接口。

实现内容:

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

技术实现:

使用 @RestController 和 @RequestMapping 注解标注控制器
使用 @Valid 注解进行参数验证
使用 @ControllerAdvice 统一处理异常
返回统一的 Result 对象

10. MetadataManager 前端组件

描述: 创建 MetadataManager 前端组件，提供元数据管理界面。

实现内容:

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

技术实现:

使用 Vue 3 和 Element Plus 进行开发
使用 Axios 调用后端 API
使用 WebSocket 实时更新任务状态
使用 Element Plus 的组件库

数据库变更

无: 本次变更不涉及数据库表结构的变更。

API 变更

新增接口

POST /metadata/retrieve - 检索元数据
- 请求参数: orgConfigId, packageXml, apiVersion
- 响应: Result
- 描述: 检索 Salesforce 元数据
POST /metadata/deploy - 部署元数据
- 请求参数: orgConfigId, zipFile, options
- 响应: Result
- 描述: 部署 Salesforce 元数据
GET /metadata/job/{jobId}/status - 获取任务状态
- 请求参数: jobId (path)
- 响应: Result
- 描述: 获取任务执行状态
DELETE /metadata/job/{jobId} - 取消任务
- 请求参数: jobId (path)
- 响应: Result
- 描述: 取消任务执行

代码变更

新增文件

后端文件:

datai-salesforce-metadata/src/main/java/com/datai/metadata/client/MetadataApiClient.java - Metadata API 客户端类
datai-salesforce-metadata/src/main/java/com/datai/metadata/client/MetadataApiException.java - Metadata API 异常类
datai-salesforce-metadata/src/main/java/com/datai/metadata/client/RetrieveResult.java - 检索结果类
datai-salesforce-metadata/src/main/java/com/datai/metadata/client/DeployResult.java - 部署结果类
datai-salesforce-metadata/src/main/java/com/datai/metadata/client/JobStatus.java - 任务状态类
datai-salesforce-metadata/src/main/java/com/datai/metadata/config/AsyncConfig.java - 异步配置类
datai-salesforce-metadata/src/main/java/com/datai/metadata/service/IMetadataApiService.java - Metadata API 服务接口
datai-salesforce-metadata/src/main/java/com/datai/metadata/service/impl/MetadataApiServiceImpl.java - Metadata API 服务实现
datai-salesforce-metadata/src/main/java/com/datai/metadata/task/MetadataPollingTask.java - Metadata 轮询任务
datai-salesforce-metadata/src/main/java/com/datai/metadata/util/ZipUtil.java - Zip 文件处理工具类
datai-salesforce-metadata/src/main/java/com/datai/metadata/util/MetadataApiUtil.java - Metadata API 工具类
datai-salesforce-metadata/src/main/java/com/datai/metadata/controller/MetadataApiController.java - Metadata API 控制器

前端文件:

datai-salesforce-metadata/src/main/resources/views/MetadataManager.vue - 元数据管理前端组件

测试文件:

datai-salesforce-metadata/src/test/java/com/datai/metadata/client/MetadataApiClientTest.java - Metadata API 客户端测试
datai-salesforce-metadata/src/test/java/com/datai/metadata/service/MetadataApiServiceImplTest.java - Metadata API 服务测试
datai-salesforce-metadata/src/test/java/com/datai/metadata/util/ZipUtilTest.java - Zip 文件处理工具测试
datai-salesforce-metadata/src/test/java/com/datai/metadata/util/MetadataApiUtilTest.java - Metadata API 工具测试
datai-salesforce-metadata/src/test/java/com/datai/metadata/controller/MetadataApiControllerTest.java - Metadata API 控制器测试

变更影响

对现有功能的影响

无影响: 本次变更新增了独立的功能模块，不影响现有功能

对数据库的影响

无修改: 未修改现有表结构

对 API 的影响

新增接口: 新增了 4 个 RESTful API 接口
无修改: 未修改现有接口

对前端的影响

新增页面: 新增了元数据管理页面
无修改: 未修改现有页面

测试结果

单元测试

✅ MetadataApiClient - 所有测试通过
✅ MetadataApiServiceImpl - 所有测试通过
✅ ZipUtil - 所有测试通过
✅ MetadataApiUtil - 所有测试通过
✅ MetadataApiController - 所有测试通过

集成测试

✅ Metadata API 客户端调用测试 - 所有测试通过
✅ 异步执行测试 - 所有测试通过
✅ 状态轮询测试 - 所有测试通过
✅ Zip 文件处理测试 - 所有测试通过
✅ 错误处理测试 - 所有测试通过

手动测试

✅ 检索元数据 - 测试通过
✅ 部署元数据 - 测试通过
✅ 查询任务状态 - 测试通过
✅ 取消任务 - 测试通过

部署说明

数据库部署

无需数据库部署。

后端部署

编译项目：mvn clean package
部署 JAR 包到服务器
启动应用：java -jar datai-salesforce-metadata.jar

前端部署

构建前端项目：npm run build
部署 dist 目录到 Web 服务器

配置更新

无需额外配置更新。

回滚方案

如果需要回滚本次变更，执行以下步骤：

删除后端代码:
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/client/ 目录下的所有文件
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/config/AsyncConfig.java
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/service/ 目录下的所有文件
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/task/MetadataPollingTask.java
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/util/ 目录下的所有文件
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/controller/MetadataApiController.java
删除前端代码:
- 删除 datai-salesforce-metadata/src/main/resources/views/MetadataManager.vue
删除测试代码:
- 删除所有相关的测试文件
重新部署: 重新编译和部署项目

审核记录

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

变更历史

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

11 KiB Raw Permalink Blame History

变更记录 - Metadata API客户端封装

变更信息

变更摘要

变更详情

新增功能

1. MetadataApiClient 客户端类

2. MetadataApiService 服务层

3. AsyncConfig 配置类

4. 状态轮询机制

5. Zip 文件处理工具类

6. MetadataApiUtil 工具类

7. 自定义异常类

8. 结果类

9. MetadataApiController 控制器

10. MetadataManager 前端组件

数据库变更

API 变更

新增接口

代码变更

新增文件

变更影响

对现有功能的影响

对数据库的影响

对 API 的影响

对前端的影响

测试结果

单元测试

集成测试

手动测试

部署说明

数据库部署

后端部署

前端部署

配置更新

回滚方案

相关文档

审核记录

变更历史

11 KiB

Raw Permalink Blame History