元数据容器与原子性部署需求

元数据

需求编号：014-4
创建时间：2026-01-26
创建人：SSOT 架构师
状态：已完成
优先级：高
父需求：REQ-014
关联代码：com.sforce.soap.tooling.MetadataContainer, com.sforce.soap.tooling.ContainerAsyncRequest, com.sforce.soap.tooling.DeployDetails

需求概述

实现基于 Tooling API 的“事务原子性”代码部署模块。通过 MetadataContainer 机制，支持将多个 Apex 类、触发器、Visualforce 页面等成员的修改打包，一次性原子部署。此机制是 Salesforce IDE 开发的核心，确保代码依赖的一致性。

目标

原子性保证：多文件修改（如 Class A 引用 Class B）必须作为一个事务提交，要么全成功，要么全失败。
编译与测试：在部署过程中自动触发编译检查，并可选执行测试用例。
状态反馈：提供详细的部署结果，包括每一行的编译错误或测试失败信息。

功能需求

1. 容器生命周期管理 (Container Lifecycle)

必须处理容器名称冲突问题（MetadataContainer Name 必须唯一）。

createContainer(String name): 创建新容器。如果同名容器已存在，应先尝试删除或使用唯一后缀生成新名称。
deleteContainer(String id): 部署完成后或发生异常时，清理容器以释放资源。

2. 成员管理 (Member Management)

支持添加多种类型的元数据成员到容器中。

addMember(String containerId, String metadataType, String contentEntityId, String body)
- metadataType: 支持 ApexClassMember, ApexTriggerMember, ApexComponentMember, ApexPageMember。
- contentEntityId: 对应 ApexClass 或 ApexTrigger 的 ID。如果是新建文件，此字段可能为空（取决于 API 版本行为，通常 Tooling API 更新需 ID）。
- body: 新的代码内容。

3. 异步部署请求 (Async Deployment)

创建 ContainerAsyncRequest 对象触发编译和部署。

deployContainer(String containerId, boolean isCheckOnly, boolean isRunTests)
- IsCheckOnly: true 仅编译验证（不保存）；false 实际保存代码。
- IsRunTests: 是否在部署后运行测试（通常用于生产环境部署或验证）。
- 返回 requestId (ContainerAsyncRequest ID)。

4. 状态轮询与结果解析 (Status Polling & Result Parsing)

由于部署是异步的，需要轮询状态并解析结果。

checkStatus(String requestId)
- 轮询 ContainerAsyncRequest 对象的 State 字段。
- 状态流转: Queued -> Processing -> Completed / Failed / Error / Invalidated / Aborted。
getDeployDetails(String requestId)
- 当状态为 Completed 或 Failed 时，读取 DeployDetails 字段。
- 解析编译错误: 遍历 DeployDetails.getComponentFailures() (对应 DeployMessage 数组)，提取 fileName, lineNumber, problem 等信息。
- 解析测试结果: 如果运行了测试，解析 DeployDetails.getRunTestResult()。

数据结构与接口定义

部署结果对象 (DeploymentResult)

public class DeploymentResult {
    private boolean success;
    private String status; // Completed, Failed, etc.
    private String errorMsg; // 系统级错误
    private List<CompilationError> compilationErrors; // 代码编译错误
}

public class CompilationError {
    private String fileName;
    private int line;
    private int column;
    private String message;
}

异常处理

容器名称冲突: 捕获 DUPLICATE_VALUE 异常，自动重试或清理旧容器。
成员添加失败: 如 contentEntityId 无效或 body 为空，应在添加阶段报错。
并发部署限制: Salesforce 允许的并发 ContainerAsyncRequest 有限，需处理排队超时情况。

技术约束

DeployDetails 引用: 必须使用 com.sforce.soap.tooling.DeployDetails 类进行反序列化。
API 版本: 确保使用的 Tooling API 版本支持当前的元数据类型。
CheckOnly 限制: CheckOnly=true 不会修改服务器代码，但会生成编译结果，适用于“保存前语法检查”。

成功标准

原子性验证: 创建一个依赖链（Class A 依赖修改后的 Class B），在同一个容器中部署成功。
错误捕获: 故意引入语法错误，部署状态应为 Failed，并能准确返回错误行号和错误信息。
CheckOnly 模式: 使用 IsCheckOnly=true 部署成功后，查询 ApexClass 内容确认未被修改。

5.1 KiB Raw Permalink Blame History Unescape Escape