5.6 KiB
5.6 KiB
架构决策记录 (ADR) 模板
背景
在 Salesforce 集成项目中，需要实现元数据的拉取和部署功能，以支持不同环境间的元数据管理和同步。该功能需要支持全量/增量部署、验证、单元测试以及破坏性变更，提高元数据管理效率。
决策
采用 Salesforce Metadata API 实现元数据拉取和部署功能，具体方案如下：
-
技术栈选择：
- 使用 Salesforce Metadata API (SOAP) 进行元数据拉取和部署
- 使用 OAuth 2.0 进行身份认证
- 采用异步处理模式处理拉取和部署请求
- 使用 Quartz 框架实现定时任务
-
架构设计：
- 分层架构：Controller 层 -> Service 层 -> Salesforce API 层
- 异步处理：拉取和部署操作异步执行，不阻塞请求线程
- 结果轮询：使用轮询机制获取异步操作结果
- 错误处理：详细记录错误信息，支持重试机制
-
数据库设计：
- 参考文档中推荐的数据库设计，包括：
- sf_org_config：存储 Salesforce 组织配置
- sf_metadata_task：定义拉取规则
- sf_job_execution：记录作业执行历史
- sf_metadata_component：记录元数据组件详情
- sf_deploy_history：记录部署历史
- 参考文档中推荐的数据库设计，包括：
-
核心功能实现：
- 元数据拉取：支持根据 package.xml 拉取指定元数据
- 元数据部署：支持全量/增量部署、验证、单元测试和破坏性变更
- 部署结果解析：详细解析部署结果，包括错误信息和代码覆盖率
- 快速部署：支持使用验证 ID 进行快速部署
备选方案
方案 1：使用 Salesforce CLI (SFDX) 命令行工具
优点：
- 命令行工具成熟稳定，支持丰富的元数据操作
- 支持插件扩展，功能强大
- 社区活跃，文档丰富
缺点：
- 需要在服务器上安装 SFDX CLI
- 命令行调用复杂度高，错误处理困难
- 集成到 Java 应用中不够优雅
- 性能和并发处理能力有限
方案 2：使用第三方库封装的 Metadata API
优点：
- 封装了复杂的 API 调用细节
- 提供更简洁的 API 接口
- 支持异步处理和结果轮询
缺点：
- 依赖第三方库，存在版本兼容风险
- 功能可能不够全面，需要自行扩展
- 学习成本较高
影响
-
系统架构：
- 增加元数据管理模块，扩展系统功能
- 引入异步处理机制，提高系统响应能力
- 增加数据库表，扩展数据模型
-
开发流程：
- 需要熟悉 Salesforce Metadata API
- 增加异步编程复杂度
- 需要实现详细的错误处理和日志记录
-
运维管理：
- 需要监控元数据拉取和部署任务
- 需要管理 Salesforce API 调用限制
- 需要处理异步任务的失败和重试
风险
-
技术风险：
- Salesforce API 版本变更可能导致兼容性问题
- 异步处理机制可能引入复杂的并发问题
- 元数据依赖关系处理复杂，可能导致部署失败
-
业务风险：
- 部署失败可能影响业务系统正常运行
- 元数据冲突可能导致数据不一致
- API 调用限制可能影响系统性能
-
实施风险：
- 开发和测试周期较长
- 需要大量的测试用例验证功能
- 需要培训开发人员熟悉相关技术
回滚策略
-
功能回滚：
- 对于部署失败的元数据，支持回滚到之前的版本
- 保存部署前的元数据快照，用于回滚
- 实现手动和自动回滚机制
-
系统回滚：
- 如果新功能引入严重问题，支持禁用元数据管理模块
- 保持系统核心功能不受影响
- 提供紧急回滚脚本
验收标准
-
功能验证：
- 成功拉取 Salesforce 元数据
- 成功部署元数据到目标组织
- 支持全量/增量部署、验证、单元测试和破坏性变更
- 提供详细的部署结果和错误信息
- 支持使用验证 ID 进行快速部署
-
性能验证：
- 拉取和部署操作异步处理，不阻塞请求线程
- 支持并发处理多个拉取和部署任务
- 满足 Salesforce API 调用限制要求
-
可靠性验证：
- 系统能够处理 API 调用失败和重试
- 详细记录错误信息，便于排查问题
- 支持任务状态查询和管理
视觉锚点
Visual Reference
- Authentication.canvas - 项目架构图
Status
- Draft
- Accepted
- Superceded