kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/changelog/20260119-metadata-api-client.md

6.9 KiB
Raw Permalink Blame History

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

变更概述

本次变更为 Metadata API 客户端封装提供了完整的实现，包括 MetadataApiClient 客户端类、retrieve() 方法、deploy() 方法、状态轮询机制、Zip 文件处理、部署结果解析、错误处理机制、异步服务接口和实现、单元测试。

变更时间

2026-01-19

变更类型

功能增强

影响范围

代码文件

客户端类

  • com.datai.salesforce.metadata.client.MetadataApiClient - Metadata API 客户端

模型类

  • com.datai.salesforce.metadata.model.RetrieveRequest - Retrieve 请求
  • com.datai.salesforce.metadata.model.RetrieveResult - Retrieve 结果
  • com.datai.salesforce.metadata.model.DeployRequest - Deploy 请求
  • com.datai.salesforce.metadata.model.DeployResult - Deploy 结果
  • com.datai.salesforce.metadata.model.DeployMessage - Deploy 消息

异常类

  • com.datai.salesforce.metadata.exception.MetadataApiException - Metadata API 异常

配置类

  • com.datai.salesforce.metadata.config.AsyncConfig - 异步配置

服务接口

  • com.datai.salesforce.metadata.service.IMetadataApiAsyncService - Metadata API 异步服务接口

服务实现

  • com.datai.salesforce.metadata.service.impl.MetadataApiAsyncServiceImpl - Metadata API 异步服务实现

单元测试

  • com.datai.salesforce.metadata.client.MetadataApiClientTest - Metadata API 客户端单元测试

文档文件

  • docs/requirements/REQ-010-5.md - Metadata API客户端封装需求文档
  • docs/decisions/adr/0014-metadata-api-client.md - Metadata API客户端封装架构决策
  • docs/prompts/005-metadata-api-client.md - Metadata API客户端封装实现提示词
  • docs/sessions/20260119-metadata-api-client.md - Metadata API客户端封装会话记录
  • docs/changelog/20260119-metadata-api-client.md - Metadata API客户端封装变更记录
  • docs/retros/20260119-metadata-api-client-retro.md - Metadata API客户端封装复盘报告

变更内容

新增功能

  1. MetadataApiClient 客户端类创建

    • 使用 Salesforce WSC (Web Service Connector) 库创建 MetadataApiClient 客户端类
    • 使用 SessionManager 进行会话管理和自动重新登录
    • 使用 WSC 库的 MetadataConnection 类创建连接
    • 使用 WSC 库的 RetrieveRequest 和 DeployRequest 类创建请求
    • 使用 WSC 库的 AsyncResult 类处理异步结果

  2. retrieve() 方法实现

    • 使用 Spring 的 @Async 注解实现异步执行
    • 使用 ThreadPoolTaskExecutor 配置线程池
    • 使用 WSC 库的 checkStatus() 方法检查任务状态
    • 使用 ScheduledExecutorService 实现轮询机制
    • 使用 ZipInputStream 处理 Zip 文件，使用流式处理避免内存溢出

  3. deploy() 方法实现

    • 使用 Spring 的 @Async 注解实现异步执行
    • 使用 ThreadPoolTaskExecutor 配置线程池
    • 使用 WSC 库的 checkStatus() 方法检查任务状态
    • 使用 ScheduledExecutorService 实现轮询机制
    • 使用 Jackson 库处理 API 响应，使用正则表达式提取错误信息

  4. 状态轮询机制

    • 使用 ScheduledExecutorService 实现定时任务
    • 使用 Future 接口支持取消操作
    • 使用 TimeoutException 处理超时情况
    • 使用指数退避算法调整轮询频率，避免 API 限流

  5. Zip 文件处理

    • 使用 ZipInputStream 处理 Zip 文件
    • 使用 BufferedInputStream 提高读取性能
    • 使用 ByteArrayOutputStream 临时存储文件内容
    • 使用 FileOutputStream 保存文件到磁盘

  6. 部署结果解析

    • 使用 Jackson 库的 ObjectMapper 类处理 API 响应
    • 使用 JsonNode 类遍历 JSON 数据
    • 使用 Pattern 和 Matcher 类提取错误信息和代码覆盖率
    • 使用自定义异常类处理部署错误

  7. 错误处理机制

    • 使用自定义异常类封装 API 调用异常
    • 使用 @Retryable 注解实现重试机制
    • 使用 Slf4j 记录错误信息
    • 使用 GlobalExceptionHandler 统一处理异常

  8. 异步服务接口和实现

    • 创建 IMetadataApiAsyncService 服务接口，定义异步服务接口
    • 创建 MetadataApiAsyncServiceImpl 服务实现，实现异步服务
    • 使用 @Async 注解实现异步执行
    • 使用 CompletableFuture 支持异步结果

  9. 单元测试

    • 创建 MetadataApiClientTest 单元测试
    • 测试 retrieve() 方法
    • 测试 deploy() 方法
    • 使用 Mockito 模拟依赖

功能改进

  • 无

Bug 修复

  • 无

性能优化

  • 无

安全改进

  • 无

代码重构

  • 无

兼容性说明

向后兼容性

本次变更为新增功能，不影响现有功能，完全向后兼容。

数据库变更

本次变更不涉及数据库结构变更，不需要数据库迁移。

API 变更

本次变更新增了以下 API 接口：

  • POST /api/metadata/retrieve - 执行 retrieve 操作
  • POST /api/metadata/deploy - 执行 deploy 操作
  • GET /api/metadata/retrieve/{id} - 查询 retrieve 状态
  • GET /api/metadata/deploy/{id} - 查询 deploy 状态
  • GET /api/metadata/retrieve/{id}/download - 下载 retrieve 结果
  • GET /api/metadata/deploy/{id}/result - 查询 deploy 结果

配置变更

本次变更需要添加以下配置：

  • 异步线程池配置
  • WSC 库依赖配置

依赖变更

新增依赖

  • com.force.api:force-wsc - Salesforce WSC 库
  • com.force.api:force-partner-api - Salesforce Partner API 库
  • com.force.api:force-metadata-api - Salesforce Metadata API 库

依赖升级

  • 无

依赖移除

  • 无

测试情况

单元测试

  • MetadataApiClientTest - 通过

集成测试

  • 待测试

性能测试

  • 待测试

安全测试

  • 待测试

已知问题

无

后续计划

  1. 进行集成测试，确保功能正常
  2. 进行性能测试，确保性能满足要求
  3. 进行安全测试，确保安全性满足要求
  4. 编写用户文档，说明如何使用 Metadata API 客户端
  5. 监控异步线程池的使用情况
  6. 监控状态轮询的频率
  7. 监控 Zip 文件处理的性能
  8. 监控 API 调用的成功率

回滚方案

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

  1. 删除所有新增的代码文件
  2. 删除所有新增的文档文件
  3. 移除 WSC 库依赖

审批信息

  • 变更申请人: SSOT 架构师
  • 变更审批人: 待审批
  • 变更执行人: SSOT 架构师
  • 变更时间: 2026-01-19

相关链接