338 lines
11 KiB
Markdown
338 lines
11 KiB
Markdown
# 变更记录 - Metadata API客户端封装
|
|
|
|
## 变更信息
|
|
|
|
- **变更编号**: Change-015
|
|
- **变更日期**: 2026-01-18
|
|
- **变更类型**: 新增功能
|
|
- **变更版本**: 0.1.17
|
|
- **相关需求**: [REQ-010-5](../requirements/REQ-010-5.md) - Metadata API客户端封装
|
|
- **相关决策**: [ADR-0014](../decisions/adr/0014-metadata-api-client.md) - Metadata API客户端封装架构决策
|
|
- **相关会话**: [Session-20260118-002](../sessions/20260118-metadata-api-client.md) - 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 变更
|
|
|
|
#### 新增接口
|
|
|
|
1. **POST /metadata/retrieve** - 检索元数据
|
|
- 请求参数: orgConfigId, packageXml, apiVersion
|
|
- 响应: Result<RetrieveResult>
|
|
- 描述: 检索 Salesforce 元数据
|
|
|
|
2. **POST /metadata/deploy** - 部署元数据
|
|
- 请求参数: orgConfigId, zipFile, options
|
|
- 响应: Result<DeployResult>
|
|
- 描述: 部署 Salesforce 元数据
|
|
|
|
3. **GET /metadata/job/{jobId}/status** - 获取任务状态
|
|
- 请求参数: jobId (path)
|
|
- 响应: Result<JobStatus>
|
|
- 描述: 获取任务执行状态
|
|
|
|
4. **DELETE /metadata/job/{jobId}** - 取消任务
|
|
- 请求参数: jobId (path)
|
|
- 响应: Result<Void>
|
|
- 描述: 取消任务执行
|
|
|
|
### 代码变更
|
|
|
|
#### 新增文件
|
|
|
|
**后端文件**:
|
|
- `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 文件处理测试 - 所有测试通过
|
|
- ✅ 错误处理测试 - 所有测试通过
|
|
|
|
### 手动测试
|
|
|
|
- ✅ 检索元数据 - 测试通过
|
|
- ✅ 部署元数据 - 测试通过
|
|
- ✅ 查询任务状态 - 测试通过
|
|
- ✅ 取消任务 - 测试通过
|
|
|
|
## 部署说明
|
|
|
|
### 数据库部署
|
|
|
|
无需数据库部署。
|
|
|
|
### 后端部署
|
|
|
|
1. 编译项目：`mvn clean package`
|
|
2. 部署 JAR 包到服务器
|
|
3. 启动应用：`java -jar datai-salesforce-metadata.jar`
|
|
|
|
### 前端部署
|
|
|
|
1. 构建前端项目：`npm run build`
|
|
2. 部署 dist 目录到 Web 服务器
|
|
|
|
### 配置更新
|
|
|
|
无需额外配置更新。
|
|
|
|
## 回滚方案
|
|
|
|
如果需要回滚本次变更，执行以下步骤：
|
|
|
|
1. **删除后端代码**:
|
|
- 删除 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
|
|
|
|
2. **删除前端代码**:
|
|
- 删除 datai-salesforce-metadata/src/main/resources/views/MetadataManager.vue
|
|
|
|
3. **删除测试代码**:
|
|
- 删除所有相关的测试文件
|
|
|
|
4. **重新部署**: 重新编译和部署项目
|
|
|
|
## 相关文档
|
|
|
|
- [REQ-010-5.md](../requirements/REQ-010-5.md) - Metadata API客户端封装需求
|
|
- [ADR-0014.md](../decisions/adr/0014-metadata-api-client.md) - Metadata API客户端封装架构决策
|
|
- [Prompt-015.md](../prompts/015-metadata-api-client.md) - Metadata API客户端封装实现提示词
|
|
- [Session-20260118-002.md](../sessions/20260118-metadata-api-client.md) - Metadata API客户端封装执行会话
|
|
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明
|
|
- [index.md](../reference-code/com/docs/index.md) - Salesforce SOAP API Java 客户端参考文档
|
|
|
|
## 审核记录
|
|
|
|
| 日期 | 审核人 | 审核结果 | 审核意见 |
|
|
|------|--------|----------|----------|
|
|
| 2026-01-18 | Datai Team | 已通过 | 变更完整，符合需求 |
|
|
|
|
## 变更历史
|
|
|
|
| 日期 | 版本 | 变更内容 | 变更人 |
|
|
|------|------|---------|--------|
|
|
| 2026-01-18 | v1.0.0 | 初始版本 | Datai Team |
|