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