设计文档

元数据

需求编号：003-04
创建时间：2026-02-03
创建人：AI Assistant
状态：进行中

设计概述

基于 Salesforce Metadata API，实现通用的异步操作管理功能。核心能力包括异步操作状态查询、自动轮询（支持超时和中断）、操作取消以及操作历史记录的持久化。该模块将作为基础服务，支持部署、检索等上层业务的异步交互需求。

架构设计

系统架构

采用标准的分层架构：

Controller 层 (MetadataAsyncController)：暴露 RESTful API，处理 HTTP 请求和响应。
Service 层 (MetadataAsyncService)：封装业务逻辑，调用 Salesforce API 进行状态检查和取消，管理轮询逻辑。
Repository 层 (MetadataAsyncRepository)：负责异步操作历史数据的持久化。
Integration 层：
- 使用 MetadataConnectionFactory 获取连接。
- 使用 metadata.jar 中的 AsyncResult 等对象。

模块依赖

datai-salesforce-auth: 提供连接管理和会话支持。
datai-salesforce-common: 提供统一异常处理和常量定义。
datai-modules-salesforce: 本模块，包含具体实现。

技术方案

技术选型

框架: Spring Boot 2.7.x
ORM: MyBatis Plus 3.5.x
Salesforce SDK: WSC (Web Service Connector) & Metadata API JAR
JSON 处理: Jackson

核心逻辑

状态轮询:
- 采用同步阻塞方式 (Thread.sleep) 在 Service 层实现轮询。
- 配置最大重试次数或超时时间（默认 5 分钟），防止无限等待。
- 轮询过程中捕获中断异常，确保线程安全。
数据持久化:
- 每次查询状态或取消操作后，异步更新数据库中的 datai_metadata_async 表。
- 记录关键信息：asyncId, status, message, timestamp。
异常处理:
- 统一捕获 ConnectionException 并转换为自定义 SalesforceOperationException。
- 识别特定错误（如 Session 过期、ID 无效）并返回对应错误码。

数据模型

数据库表设计

表名: datai_metadata_async

字段名	类型	说明	约束
id	BIGINT	主键	PRIMARY KEY, AUTO_INCREMENT
async_id	VARCHAR(100)	异步操作 ID	NOT NULL
status	VARCHAR(50)	操作状态	NOT NULL
done	BOOLEAN	是否完成	DEFAULT FALSE
message	TEXT	操作消息
error_message	TEXT	错误消息
create_time	DATETIME	创建时间	DEFAULT CURRENT_TIMESTAMP
update_time	DATETIME	更新时间	DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
user_id	VARCHAR(50)	用户 ID

索引:

idx_async_id: async_id
idx_status: status

实体类设计

MetadataAsyncEntity 继承自 BaseEntity (若依规范):

@TableName("datai_metadata_async")
public class MetadataAsyncEntity extends BaseEntity {
    @TableId
    private Long id;
    private String asyncId;
    private String status;
    private Boolean done;
    private String message;
    private String errorMessage;
    private String userId;
}

接口设计

RESTful API

获取状态
- GET /api/metadata/async/status/{asyncId}
- 响应：ApiResponse<AsyncResult>
轮询状态
- GET /api/metadata/async/poll/{asyncId}?interval=5000&timeout=300000
- 响应：ApiResponse<AsyncResult>
取消操作
- POST /api/metadata/async/cancel/{asyncId}
- 响应：ApiResponse<CancelResult>
获取历史
- GET /api/metadata/async/history?limit=10
- 响应：ApiResponse<List<MetadataAsyncEntity>>

实现要点

Service 不依赖具体类型: getAsyncResult 和 checkStatus 应设计为通用方法，不绑定特定的 Metadata 类型（如 CustomObject）。
轮询防死锁: 确保超时机制在任何情况下都能触发（使用 System.currentTimeMillis() 检查）。
状态映射: Salesforce 的状态 (Queued, InProgress, Completed, Error) 需准确映射到数据库字段。

4.3 KiB Raw Permalink Blame History Unescape Escape