kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/REQ-010-5.md

12 KiB
Raw Permalink Blame History

Requirements - Metadata API客户端封装

需求信息

  • 需求名称: Metadata API客户端封装
  • 需求类型: 功能需求
  • 需求编号: REQ-010-5
  • 父需求: REQ-010
  • 创建日期: 2026-01-17
  • 需求版本: v1.0.0
  • 需求提出人: 系统管理员
  • 需求状态: 已完成

输入引用

引用相关的 docs 文档链接：

Context Maps

强制列出本次需求依赖的 Canvas 文件：

需求目标

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

需求描述

概述

本需求旨在封装Salesforce Metadata API客户端，提供retrieve()和deploy()方法的调用接口，支持异步执行、状态轮询、Job ID获取、Zip文件下载、部署结果解析、错误处理机制等。

详细需求

1. MetadataApiClient客户端类创建

  • 需求描述: 创建MetadataApiClient客户端类，封装Salesforce Metadata API调用
  • 优先级: 高
  • 验收标准:
    • MetadataApiClient创建成功
    • 使用Salesforce WSC (Web Service Connector)库
    • 与SessionManager集成成功
    • 使用WSC库的MetadataConnection类创建连接
    • 使用WSC库的RetrieveRequest和DeployRequest类创建请求
    • 使用WSC库的AsyncResult类处理异步结果
    • 代码符合项目编码规范
  • 依赖关系: 依赖于REQ-010-1, REQ-010-2
  • 实现建议: 使用Salesforce WSC库，参考官方Java示例代码，使用SessionManager进行会话管理和自动重新登录

2. retrieve()方法实现

  • 需求描述: 实现retrieve()方法调用，支持异步执行
  • 优先级: 高
  • 验收标准:
    • retrieve()方法调用成功
    • 支持异步执行（使用@Async注解）
    • 支持Job ID获取
    • 支持状态轮询（使用ScheduledExecutorService）
    • 支持Zip文件下载
    • 支持超时处理
    • 支持取消操作
    • 错误处理机制正常工作
    • 使用ZipInputStream处理Zip文件，使用流式处理避免内存溢出
  • 依赖关系: 依赖于MetadataApiClient客户端类创建
  • 实现建议: 使用异步线程池执行长时间任务，使用轮询机制检查任务状态，使用指数退避算法调整轮询频率

3. deploy()方法实现

  • 需求描述: 实现deploy()方法调用，支持异步执行
  • 优先级: 高
  • 验收标准:
    • deploy()方法调用成功
    • 支持异步执行（使用@Async注解）
    • 支持Job ID获取
    • 支持状态轮询（使用ScheduledExecutorService）
    • 支持部署结果解析
    • 支持超时处理
    • 支持取消操作
    • 错误处理机制正常工作
    • 使用Jackson库处理API响应，使用正则表达式提取错误信息
  • 依赖关系: 依赖于MetadataApiClient客户端类创建
  • 实现建议: 使用异步线程池执行长时间任务，使用轮询机制检查任务状态，使用指数退避算法调整轮询频率

4. 状态轮询机制

  • 需求描述: 实现状态轮询机制，检查任务执行状态
  • 优先级: 高
  • 验收标准:
    • 状态轮询机制正常工作
    • 轮询频率合理（使用指数退避算法）
    • 支持超时处理
    • 支持取消轮询
    • 避免API限流
    • 使用ScheduledExecutorService实现定时任务
    • 使用Future接口支持取消操作
  • 依赖关系: 依赖于retrieve()和deploy()方法实现
  • 实现建议: 使用定时任务实现轮询，使用超时机制防止无限轮询，使用指数退避算法调整轮询频率

5. Zip文件处理

  • 需求描述: 实现Zip文件下载和解压处理
  • 优先级: 高
  • 验收标准:
    • Zip文件下载成功
    • Zip文件解压成功
    • 支持大文件处理
    • 内存使用合理
    • 使用ZipInputStream处理Zip文件
    • 使用BufferedInputStream提高读取性能
    • 使用ByteArrayOutputStream临时存储文件内容
    • 使用FileOutputStream保存文件到磁盘
  • 依赖关系: 依赖于retrieve()方法实现
  • 实现建议: 使用ZipInputStream处理Zip文件，使用流式处理避免内存溢出

6. 部署结果解析

  • 需求描述: 实现部署结果解析，提取错误信息和代码覆盖率
  • 优先级: 高
  • 验收标准:
    • 部署结果解析成功
    • 错误信息提取正确
    • 代码覆盖率提取正确
    • 支持多种部署状态
    • 使用Jackson库的ObjectMapper类处理API响应
    • 使用JsonNode类遍历JSON数据
    • 使用Pattern和Matcher类提取错误信息和代码覆盖率
  • 依赖关系: 依赖于deploy()方法实现
  • 实现建议: 使用JSON解析库处理API响应，使用正则表达式提取错误信息

7. 错误处理机制

  • 需求描述: 实现错误处理机制，捕获和处理API调用异常
  • 优先级: 高
  • 验收标准:
    • 错误处理机制正常工作
    • 支持多种异常类型
    • 错误信息详细
    • 支持错误重试
    • 使用自定义异常类封装API调用异常
    • 使用@Retryable注解实现重试机制
    • 使用Slf4j记录错误信息
    • 使用GlobalExceptionHandler统一处理异常
  • 依赖关系: 依赖于所有API方法实现
  • 实现建议: 使用统一的异常处理机制，使用重试机制处理网络异常

8. 异步服务接口和实现

  • 需求描述: 创建异步服务接口和实现，支持异步执行
  • 优先级: 高
  • 验收标准:
    • IMetadataApiAsyncService服务接口创建成功
    • MetadataApiAsyncServiceImpl服务实现创建成功
    • 使用@Async注解实现异步执行
    • 使用CompletableFuture支持异步结果
    • 异步执行不影响系统响应
  • 依赖关系: 依赖于MetadataApiClient客户端类创建
  • 实现建议: 使用Spring的@Async注解实现异步执行，使用ThreadPoolTaskExecutor配置线程池

约束

  • 技术栈限制: 必须使用Salesforce WSC (Web Service Connector)库
  • 架构约束: 必须遵循Authentication.canvas中定义的架构和调用关系
  • 模块约束: 必须在datai-salesforce-metadata模块下实现
  • 认证约束: 必须使用SessionManager进行会话管理和自动重新登录
  • API约束: 必须遵循Salesforce Metadata API调用规范
  • 异步约束: 必须使用异步线程池执行长时间任务
  • 依赖约束: 必须依赖于REQ-010-1, REQ-010-2
  • 代码结构约束: 必须按照以下代码结构组织代码 
    datai-salesforce-metadata/
├── src/main/java/com/datai/metadata/
│   ├── client/
│   │   ├── MetadataApiClient.java - Metadata API 客户端类
│   │   ├── MetadataApiException.java - Metadata API 异常类
│   │   ├── RetrieveResult.java - 检索结果类
│   │   ├── DeployResult.java - 部署结果类
│   │   └── JobStatus.java - 任务状态类
│   ├── config/
│   │   └── AsyncConfig.java - 异步配置类
│   ├── service/
│   │   ├── IMetadataApiService.java - Metadata API 服务接口
│   │   └── impl/
│   │       └── MetadataApiServiceImpl.java - Metadata API 服务实现
│   ├── task/
│   │   └── MetadataPollingTask.java - Metadata 轮询任务
│   └── util/
│       ├── ZipUtil.java - Zip 文件处理工具类
│       └── MetadataApiUtil.java - Metadata API 工具类
  • WSC库使用约束: 必须使用WSC库的以下类
    • MetadataConnection类创建连接
    • RetrieveRequest和DeployRequest类创建请求
    • AsyncResult类处理异步结果
    • checkStatus()方法检查任务状态
  • 异步执行约束: 必须使用Spring的@Async注解实现异步执行
  • 线程池约束: 必须使用ThreadPoolTaskExecutor配置线程池
  • 轮询机制约束: 必须使用ScheduledExecutorService实现轮询机制
  • Zip处理约束: 必须使用ZipInputStream处理Zip文件，使用流式处理避免内存溢出
  • JSON处理约束: 必须使用Jackson库处理API响应
  • 异常处理约束: 必须使用统一的异常处理机制，使用@Retryable注解实现重试机制

Rule Set

"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"

具体规则：

  • 必须使用Canvas中定义的类名和方法名
  • 必须遵循Canvas中定义的调用关系
  • 必须参考Canvas中的流程图逻辑
  • 必须使用SessionManager进行会话管理和自动重新登录
  • 必须使用现有的认证模块进行OAuth认证
  • 必须使用现有的集成核心功能进行API调用
  • 必须遵循现有的异常处理机制
  • 必须遵循现有的日志记录规范

验收标准

  • 功能完整性: 所有API方法能够正常工作，异步执行机制正常
  • 代码规范性: 代码符合项目编码规范，有清晰的注释
  • 性能要求: 异步执行不影响系统响应，轮询频率合理
  • 可维护性: 代码结构清晰，易于扩展和维护
  • 可测试性: 代码易于单元测试和集成测试

风险

  • WSC库版本风险: WSC库版本兼容性问题，需要选择稳定的版本
  • WSC库学习曲线: WSC库使用复杂，开发人员需要时间学习
  • 异步执行风险: 异步执行机制复杂可能导致状态管理困难
  • 状态轮询风险: 状态轮询频率不当可能导致API限流
  • 轮询超时风险: 轮询超时设置不当可能导致任务失败
  • 指数退避算法风险: 指数退避算法参数设置不当可能导致轮询效率低下
  • Zip文件处理风险: Zip文件处理不当可能导致内存溢出
  • 大文件处理风险: 大文件处理可能导致系统性能下降
  • 错误处理风险: 错误处理不完善可能导致任务失败无法恢复
  • 重试机制风险: 重试机制设置不当可能导致无限重试
  • JSON解析风险: JSON解析错误可能导致部署结果解析失败
  • 正则表达式风险: 正则表达式错误可能导致错误信息提取失败
  • SessionManager集成风险: SessionManager集成不当可能导致认证失败
  • 线程池配置风险: 线程池配置不当可能导致系统资源耗尽
  • CompletableFuture风险: CompletableFuture使用不当可能导致异步结果丢失
  • 单元测试风险: 单元测试不完善可能导致代码质量问题

需求变更记录

日期 变更内容 变更原因 变更人 审核人 状态
2026-01-17 创建需求文档 初始需求 系统管理员 - 待审核
2026-01-18 完成需求实现 完成6个阶段的开发流程 Datai Team - 已完成

相关人员

  • 需求提出人: 系统管理员 - 联系方式
  • 需求负责人: 系统管理员 - 联系方式
  • 技术负责人: 开发工程师 - 联系方式
  • 测试负责人: 测试工程师 - 联系方式
  • 其他相关人员: - 联系方式

评审信息

  • 评审日期: -
  • 评审人员: -
  • 评审结果: -
  • 评审意见: -
  • 修改建议: -