3.9 KiB
3.9 KiB
ADR-003-02: 元数据部署技术选型
状态
已接受
日期
2026-02-03
背景
在 Salesforce Metadata API 集成中，"部署"（Deploy）是一个核心且复杂的操作。它要求客户端构建一个符合特定结构的 ZIP 压缩包，其中包含 package.xml 描述文件和具体的元数据文件（XML 格式）。
我们需要确定以下技术方案：
- XML 序列化方案：如何将 Java 对象转换为 Metadata API 要求的 XML 格式。
- 压缩包构建方案：如何构建符合 Salesforce 要求的 ZIP 包。
- 部署交互模式：如何处理 Metadata API 的异步特性（Deploy 是异步操作）。
决策
选择方案 1：JAXB + Java Util Zip + 同步轮询封装。
理由
- 标准化与兼容性：Salesforce Metadata API 的 WSC (Web Service Connector) 客户端库生成的 Java 类通常基于 XML 标准。使用 JAXB (Java Architecture for XML Binding) 是处理这些对象的原生方式，能够精确控制 XML 命名空间和结构，确保与 Salesforce 服务端的兼容性。
- 依赖最小化：
java.util.zip是 JDK 标准库，无需引入额外依赖（如 Apache Commons Compress），足以满足构建标准 ZIP 包的需求。 - 前端交互简化：虽然 Metadata API 的
deploy操作是异步的（返回AsyncResult），但在本项目的业务场景中，用户通常需要即时反馈部署结果。在 Service 层实现"同步轮询"（提交后循环检查状态直到完成或超时），可以将复杂的异步状态管理封装在后端，向前端暴露一个简单的同步 REST API，降低前端开发复杂度。 - 一致性：项目中已有的连接管理等模块倾向于使用标准 Java API 和 Spring Boot 生态，此方案保持了技术栈的一致性。
后果
正面影响
- 开发效率：利用 JAXB 注解可以快速定义和调整元数据结构，无需手动拼接 XML 字符串。
- 维护性：代码结构清晰，Service 层封装了复杂的轮询逻辑，Controller 层保持轻量。
- 前端友好：前端无需实现轮询逻辑，只需等待 HTTP 响应即可获取最终部署结果（成功/失败/部分失败）。
负面影响
- 服务器资源占用：同步轮询会占用后端线程资源。如果部署时间过长（如超过 HTTP 超时时间），可能会导致连接断开。
- 缓解措施：设置合理的轮询超时时间（如 2 分钟），对于超大型部署建议后续扩展为纯异步模式。
- JAXB 依赖管理：在 JDK 9+ 中 JAXB 被移除，需要额外引入
jaxb-api和实现库（项目中已有相关依赖）。
替代方案
方案 2：Jackson XML + Apache Commons Compress + 纯异步回调
- 技术栈：使用 Jackson XML 处理 XML，Commons Compress 处理 ZIP，前端轮询或 Webhook 回调。
- 优点：Jackson 是 Spring Boot 默认 JSON 库，统一使用可能减少依赖；纯异步模式对后端线程更友好。
- 缺点：
- Salesforce WSC 生成的类通常不带 Jackson 注解，需要重新定义 DTO 或手动配置 Mapper，工作量大且易错。
- 纯异步模式要求前端实现轮询或后端暴露公网回调地址（Webhook），增加了系统复杂度和部署难度。
- 适用场景：超大规模元数据部署，或对高并发有极高要求的场景。
方案 3：手动拼接字符串
- 技术栈：使用 StringBuilder 手动构建 XML。
- 优点：性能最高，无任何序列化库依赖。
- 缺点：极易出错（转义字符、命名空间处理），代码难以维护，可读性差。
- 适用场景：仅在极简单的 XML 结构且对性能有极致要求时考虑。