266 lines
11 KiB
Markdown
266 lines
11 KiB
Markdown
# 架构决策记录 - Destructive Changes功能实现
|
||
|
||
## 背景
|
||
|
||
REQ-010-10 要求实现 Destructive Changes 功能，支持部署时删除指定的元数据组件，使用 destructiveChanges.xml 配置删除规则。Destructive Changes 是 Salesforce Metadata API 提供的一个特殊功能，允许用户在部署时删除指定的元数据组件，如 Custom Object、Custom Field、Apex Class、Visualforce Page 等。
|
||
|
||
当前系统已经实现了元数据部署核心功能（REQ-010-8），包括手动触发部署、异步部署执行、状态监控、部署历史记录、部署进度查询、部署取消功能和部署结果解析。Destructive Changes 功能需要基于现有的部署核心功能，提供删除元数据组件的能力。
|
||
|
||
## 决策
|
||
|
||
### 1. destructiveChanges.xml 配置方案
|
||
|
||
**决策**: 使用 XML 解析库处理 destructiveChanges.xml，提供可视化编辑器，支持多种元数据类型配置和通配符配置。
|
||
|
||
**理由**:
|
||
- XML 是 Salesforce Metadata API 的标准配置格式，易于理解和维护
|
||
- 可视化编辑器可以提高用户体验，降低配置错误率
|
||
- 支持多种元数据类型配置，满足不同的删除需求
|
||
- 支持通配符配置，提高配置灵活性
|
||
- XML 解析库可以方便地解析和验证 destructiveChanges.xml
|
||
|
||
**实现方案**:
|
||
- 创建 DestructiveChangesConfigService 服务接口
|
||
- 创建 DestructiveChangesConfigServiceImpl 服务实现
|
||
- 使用 Java XML 解析库（如 JAXB 或 DOM4J）处理 destructiveChanges.xml
|
||
- 提供可视化编辑器，支持添加、删除、修改删除规则
|
||
- 提供验证功能，验证 destructiveChanges.xml 格式和删除规则
|
||
|
||
### 2. Destructive Changes 部署方案
|
||
|
||
**决策**: 使用 RESTful API 接口实现 Destructive Changes 部署，调用 MetadataApiClient 的 deploy() 方法，传入 destructiveChanges.xml。
|
||
|
||
**理由**:
|
||
- RESTful API 是标准的接口设计模式，易于使用和理解
|
||
- 可以与前端组件无缝集成
|
||
- 支持多种客户端（Web、移动端、第三方应用）
|
||
- 符合项目现有的 API 设计规范
|
||
- 基于现有的部署核心功能，复用 deploy() 方法
|
||
|
||
**实现方案**:
|
||
- 创建 DestructiveChangesController 控制器
|
||
- 提供 POST /metadata/destructive-changes/deploy 接口
|
||
- 接收任务ID、组织配置ID和 destructiveChanges.xml 作为参数
|
||
- 调用 MetadataApiService 的 deployDestructiveChangesAsync() 方法
|
||
- 返回 Job ID 和初始状态
|
||
|
||
### 3. Destructive Changes 验证方案
|
||
|
||
**决策**: 使用 XML 解析库验证 destructiveChanges.xml 格式，使用正则表达式验证删除规则，提供详细的错误信息。
|
||
|
||
**理由**:
|
||
- XML 解析库可以方便地验证 destructiveChanges.xml 格式
|
||
- 正则表达式可以灵活地验证删除规则，适应不同的元数据类型
|
||
- 详细的错误信息可以帮助用户快速定位和解决问题
|
||
- 与现有的验证机制保持一致的设计模式
|
||
- 易于扩展和维护
|
||
|
||
**实现方案**:
|
||
- 使用 Java XML 解析库（如 JAXB 或 DOM4J）验证 destructiveChanges.xml 格式
|
||
- 使用正则表达式验证删除规则
|
||
- 提供详细的错误信息，包括错误位置和错误原因
|
||
- 支持批量验证，提高验证效率
|
||
|
||
### 4. Destructive Changes 历史记录方案
|
||
|
||
**决策**: 使用 MyBatis Plus 的 BaseMapper 实现 Destructive Changes 历史记录查询，支持分页查询和条件查询。
|
||
|
||
**理由**:
|
||
- MyBatis Plus 是项目现有的持久层框架，符合技术栈要求
|
||
- BaseMapper 提供了丰富的查询方法，易于使用
|
||
- 支持分页查询，避免一次性加载大量数据
|
||
- 支持条件查询，灵活满足不同的查询需求
|
||
- 与现有的部署历史记录保持一致的设计模式
|
||
|
||
**实现方案**:
|
||
- 使用 DataiMetaJobExecution 表存储 Destructive Changes 历史记录
|
||
- 使用 jobType 字段区分 Destructive Changes 和普通部署
|
||
- 使用 MyBatis Plus 的 BaseMapper 实现查询
|
||
- 使用 Page 对象实现分页查询
|
||
- 使用 QueryWrapper 实现条件查询
|
||
|
||
### 5. Destructive Changes 回滚方案
|
||
|
||
**决策**: 使用备份的元数据组件进行回滚，使用事务确保回滚原子性，提供回滚日志记录。
|
||
|
||
**理由**:
|
||
- 备份的元数据组件可以确保回滚的完整性和准确性
|
||
- 事务可以确保回滚的原子性，避免部分回滚导致数据不一致
|
||
- 回滚日志记录可以追踪回滚历史，便于审计和问题排查
|
||
- 与现有的部署机制保持一致的设计模式
|
||
- 易于扩展和维护
|
||
|
||
**实现方案**:
|
||
- 在删除元数据组件之前，先备份元数据组件
|
||
- 使用事务确保回滚的原子性
|
||
- 提供回滚日志记录，记录回滚的详细信息
|
||
- 支持批量回滚，提高回滚效率
|
||
- 提供回滚验证功能，验证回滚的完整性
|
||
|
||
## 备选方案
|
||
|
||
### 方案 1: 使用 JSON 格式配置删除规则
|
||
|
||
**优点**:
|
||
- JSON 格式更简洁，易于读写
|
||
- JSON 解析库性能更好
|
||
- 更适合前端处理
|
||
|
||
**缺点**:
|
||
- 不符合 Salesforce Metadata API 的标准格式
|
||
- 需要额外的转换逻辑
|
||
- 与 Salesforce 官方文档不一致
|
||
|
||
**未选择原因**: XML 是 Salesforce Metadata API 的标准配置格式，使用 JSON 格式会增加额外的转换逻辑，不符合官方规范。
|
||
|
||
### 方案 2: 使用数据库存储删除规则
|
||
|
||
**优点**:
|
||
- 易于查询和管理
|
||
- 支持复杂查询
|
||
- 易于扩展
|
||
|
||
**缺点**:
|
||
- 不符合 Salesforce Metadata API 的标准格式
|
||
- 需要额外的转换逻辑
|
||
- 与 Salesforce 官方文档不一致
|
||
|
||
**未选择原因**: XML 是 Salesforce Metadata API 的标准配置格式，使用数据库存储会增加额外的转换逻辑，不符合官方规范。
|
||
|
||
### 方案 3: 不提供回滚功能
|
||
|
||
**优点**:
|
||
- 简化实现，降低复杂度
|
||
- 减少存储开销
|
||
- 提高性能
|
||
|
||
**缺点**:
|
||
- 删除操作不可逆，风险高
|
||
- 无法恢复误删除的数据
|
||
- 不符合最佳实践
|
||
|
||
**未选择原因**: 删除操作不可逆风险太高，必须提供回滚功能，确保数据安全。
|
||
|
||
## 影响
|
||
|
||
### 系统架构影响
|
||
|
||
- **新增模块**: DestructiveChangesController、IDestructiveChangesService、DestructiveChangesServiceImpl、IDestructiveChangesConfigService、DestructiveChangesConfigServiceImpl
|
||
- **现有模块**: MetadataApiClient 需要支持传入 destructiveChanges.xml
|
||
- **数据库**: 使用现有的 DataiMetaJobExecution 表，新增字段存储备份信息
|
||
- **API**: 新增 5 个 RESTful API 接口
|
||
|
||
### 开发流程影响
|
||
|
||
- **开发工作量**: 中等，复用现有的部署核心功能代码
|
||
- **测试工作量**: 高，需要测试删除和回滚的各种场景
|
||
- **文档工作量**: 中等，需要编写配置说明和使用文档
|
||
|
||
### 运维管理影响
|
||
|
||
- **部署复杂度**: 低，与现有部署流程一致
|
||
- **监控复杂度**: 低，复用现有的监控机制
|
||
- **日志复杂度**: 中等，需要记录删除和回滚的详细日志
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
|
||
- **删除操作风险**: 删除操作不可逆可能导致数据丢失
|
||
- **缓解措施**: 提供备份和回滚功能，使用事务确保删除和回滚的原子性
|
||
- **验证风险**: 验证逻辑不完善可能导致误删除
|
||
- **缓解措施**: 仔细验证 destructiveChanges.xml 格式和删除规则，提供详细的错误信息
|
||
- **回滚风险**: 回滚功能不完善可能导致无法恢复
|
||
- **缓解措施**: 使用备份的元数据组件进行回滚，使用事务确保回滚的原子性，提供回滚验证功能
|
||
|
||
### 业务风险
|
||
|
||
- **数据丢失风险**: 删除操作可能导致数据丢失
|
||
- **缓解措施**: 提供备份和回滚功能，记录详细的删除和回滚日志
|
||
- **误删除风险**: 验证不完善可能导致误删除
|
||
- **缓解措施**: 提供详细的错误信息，支持预验证功能
|
||
- **回滚失败风险**: 回滚功能不完善可能导致无法恢复
|
||
- **缓解措施**: 使用事务确保回滚的原子性，提供回滚验证功能
|
||
|
||
### 实施风险
|
||
|
||
- **依赖风险**: 依赖于 REQ-010-1, REQ-010-2, REQ-010-8
|
||
- **缓解措施**: 确保依赖的需求已经完成，避免依赖问题
|
||
|
||
## 回滚策略
|
||
|
||
如果 Destructive Changes 功能实施后出现问题，可以采取以下回滚策略：
|
||
|
||
1. **禁用 Destructive Changes 功能**: 通过配置开关禁用 Destructive Changes 功能，回退到普通部署
|
||
2. **删除 Destructive Changes 相关代码**: 删除 DestructiveChangesController、IDestructiveChangesService、DestructiveChangesServiceImpl、IDestructiveChangesConfigService、DestructiveChangesConfigServiceImpl 等代码
|
||
3. **清理 Destructive Changes 历史记录**: 清理 DataiMetaJobExecution 表中的 Destructive Changes 记录
|
||
4. **恢复 API**: 删除 Destructive Changes 相关的 API 接口
|
||
5. **恢复备份**: 使用备份的元数据组件恢复被删除的数据
|
||
|
||
## 验收标准
|
||
|
||
### 功能验收标准
|
||
|
||
- destructiveChanges.xml 配置成功，支持可视化编辑
|
||
- destructiveChanges.xml 格式符合 Salesforce Metadata API 规范
|
||
- 支持多种元数据类型配置
|
||
- 支持通配符配置
|
||
- destructiveChanges.xml 验证功能正常工作
|
||
- Destructive Changes 部署成功，支持删除指定的元数据组件
|
||
- 支持批量删除
|
||
- 删除操作安全可靠
|
||
- API 接口符合 RESTful 规范
|
||
- Destructive Changes 验证功能正常工作
|
||
- destructiveChanges.xml 格式验证正确
|
||
- 删除规则验证正确
|
||
- 验证失败返回详细错误信息
|
||
- Destructive Changes 历史记录成功
|
||
- 支持分页查询
|
||
- 支持条件查询
|
||
- 历史记录完整
|
||
- Destructive Changes 回滚功能正常工作
|
||
- 支持恢复被删除的元数据组件
|
||
- 回滚操作安全可靠
|
||
- 回滚日志记录完整
|
||
|
||
### 性能验收标准
|
||
|
||
- destructiveChanges.xml 配置响应时间 < 1s
|
||
- Destructive Changes 部署触发响应时间 < 1s
|
||
- Destructive Changes 验证响应时间 < 500ms
|
||
- Destructive Changes 历史记录查询响应时间 < 1s
|
||
- Destructive Changes 回滚响应时间 < 2s
|
||
|
||
### 代码质量验收标准
|
||
|
||
- 代码符合项目编码规范，有清晰的注释
|
||
- 单元测试覆盖率 > 80%
|
||
- 集成测试通过率 100%
|
||
- 无严重的代码质量问题
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **具体节点**: [IMetadataApiService](node_metadata_api_service) - 元数据API服务接口
|
||
- **具体节点**: [MetadataApiClient](node_metadata_api_client) - Metadata API客户端
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
||
|
||
- [REQ-010-10.md](../requirements/REQ-010-10.md) - Destructive Changes功能实现需求文档
|
||
- [REQ-010-8.md](../requirements/REQ-010-8.md) - 元数据部署核心功能需求文档
|
||
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明
|
||
- [004-元数据部署网页资料链接地址](../reference-code/metadata/004-元数据部署网页资料链接地址) - 官方文档和开源项目参考
|
||
- [Salesforce Metadata API Destructive Changes](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_destructivechanges.htm) - Salesforce 官方文档
|