Kris
2e6f087732
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段 - 创建ADR文档：0026-performance-optimization.md - 创建Prompt文档：027-performance-optimization.md - 创建会话记录：20260119-performance-optimization.md - 创建变更记录：20260119-performance-optimization.md - 创建复盘报告：20260119-performance-optimization-retro.md - 更新index.md和CHANGELOG.md - 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段 - 更新ADR文档：0011-entity-mapper-create.md - 创建Prompt文档：002-entity-mapper-create.md - 更新index.md 所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
262 lines
10 KiB
Markdown
262 lines
10 KiB
Markdown
# 架构决策记录 - 元数据组件索引和查询
|
||
|
||
## 背景
|
||
|
||
REQ-010-11 要求实现元数据组件索引和查询功能，支持按类型、名称、版本等条件查询元数据组件。元数据组件索引和查询是 Salesforce 元数据管理的重要功能，可以帮助用户快速查找和管理元数据组件。
|
||
|
||
当前系统已经实现了文件存储和解压处理（REQ-010-7），包括 Zip 文件存储、文件解压、文件路径管理。元数据组件索引和查询功能需要基于现有的文件存储和解压处理，提供元数据组件的索引和查询能力。
|
||
|
||
## 决策
|
||
|
||
### 1. 组件索引创建方案
|
||
|
||
**决策**: 使用文件解析库解析元数据文件，使用 MyBatis Plus 批量插入索引数据，支持多种元数据类型解析。
|
||
|
||
**理由**:
|
||
- 文件解析库可以方便地解析各种格式的元数据文件（XML、JSON、Apex、Visualforce 等）
|
||
- MyBatis Plus 批量插入可以提高索引创建的性能
|
||
- 支持多种元数据类型解析，满足不同的索引需求
|
||
- 索引信息完整准确，便于后续查询
|
||
- 与现有的文件存储和解压处理保持一致的设计模式
|
||
|
||
**实现方案**:
|
||
- 创建 IMetadataComponentIndexService 服务接口
|
||
- 创建 MetadataComponentIndexServiceImpl 服务实现
|
||
- 使用 Java 文件解析库（如 Jackson、DOM4J）解析元数据文件
|
||
- 使用 MyBatis Plus 的 saveBatch() 方法批量插入索引数据
|
||
- 支持异步索引创建，提高索引创建性能
|
||
- 提供索引创建进度回调，实时反馈索引创建进度
|
||
|
||
### 2. 组件查询方案
|
||
|
||
**决策**: 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，使用分页插件实现分页，支持按类型、名称、版本等条件查询。
|
||
|
||
**理由**:
|
||
- MyBatis Plus 是项目现有的持久层框架，符合技术栈要求
|
||
- QueryWrapper 提供了丰富的查询方法，易于使用
|
||
- 支持多条件组合查询，灵活满足不同的查询需求
|
||
- 支持分页查询，避免一次性加载大量数据
|
||
- 与现有的查询机制保持一致的设计模式
|
||
- 易于扩展和维护
|
||
|
||
**实现方案**:
|
||
- 创建 IMetadataComponentQueryService 服务接口
|
||
- 创建 MetadataComponentQueryServiceImpl 服务实现
|
||
- 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询
|
||
- 使用 MyBatis Plus 的分页插件实现分页查询
|
||
- 支持按类型查询
|
||
- 支持按名称查询
|
||
- 支持按版本查询
|
||
- 支持多条件组合查询
|
||
- 支持模糊查询
|
||
|
||
### 3. 组件详情查看方案
|
||
|
||
**决策**: 使用文件读取 API 读取组件文件内容，使用关系查询获取组件依赖关系，支持查看组件文件内容和依赖关系。
|
||
|
||
**理由**:
|
||
- 文件读取 API 可以方便地读取组件文件内容
|
||
- 关系查询可以获取组件依赖关系，提供完整的组件信息
|
||
- 支持查看组件文件内容，便于用户了解组件的详细信息
|
||
- 支持查看组件依赖关系，便于用户了解组件的依赖情况
|
||
- 与现有的文件存储和查询机制保持一致的设计模式
|
||
- 易于扩展和维护
|
||
|
||
**实现方案**:
|
||
- 创建 IMetadataComponentDetailService 服务接口
|
||
- 创建 MetadataComponentDetailServiceImpl 服务实现
|
||
- 使用文件读取 API 读取组件文件内容
|
||
- 使用关系查询获取组件依赖关系
|
||
- 提供组件详情查询接口
|
||
- 提供组件文件内容查询接口
|
||
- 提供组件依赖关系查询接口
|
||
|
||
### 4. 组件统计方案
|
||
|
||
**决策**: 使用 MyBatis Plus 的聚合查询实现统计功能，支持按类型、版本、组织等维度统计。
|
||
|
||
**理由**:
|
||
- MyBatis Plus 是项目现有的持久层框架，符合技术栈要求
|
||
- 聚合查询可以方便地实现统计功能
|
||
- 支持按类型统计，了解组件类型分布
|
||
- 支持按版本统计，了解组件版本分布
|
||
- 支持按组织统计，了解不同组织的组件情况
|
||
- 与现有的查询机制保持一致的设计模式
|
||
- 易于扩展和维护
|
||
|
||
**实现方案**:
|
||
- 创建 IMetadataComponentStatisticsService 服务接口
|
||
- 创建 MetadataComponentStatisticsServiceImpl 服务实现
|
||
- 使用 MyBatis Plus 的聚合查询实现统计功能
|
||
- 提供组件总数统计接口
|
||
- 提供组件类型分布统计接口
|
||
- 提供组件版本分布统计接口
|
||
- 提供组件组织分布统计接口
|
||
|
||
## 备选方案
|
||
|
||
### 方案 1: 使用搜索引擎实现组件查询
|
||
|
||
**优点**:
|
||
- 查询性能更好
|
||
- 支持全文搜索
|
||
- 支持复杂的查询条件
|
||
|
||
**缺点**:
|
||
- 增加系统复杂度
|
||
- 需要额外的搜索引擎基础设施
|
||
- 增加运维成本
|
||
- 与现有的查询机制不一致
|
||
|
||
**未选择原因**: MyBatis Plus 的查询性能已经能够满足需求，使用搜索引擎会增加不必要的复杂度。
|
||
|
||
### 方案 2: 使用缓存提高查询性能
|
||
|
||
**优点**:
|
||
- 查询性能更好
|
||
- 减少数据库查询
|
||
- 提高系统响应速度
|
||
|
||
**缺点**:
|
||
- 增加系统复杂度
|
||
- 需要额外的缓存基础设施
|
||
- 增加运维成本
|
||
- 缓存一致性难以保证
|
||
|
||
**未选择原因**: MyBatis Plus 的查询性能已经能够满足需求，使用缓存会增加不必要的复杂度。
|
||
|
||
### 方案 3: 使用 NoSQL 数据库存储组件索引
|
||
|
||
**优点**:
|
||
- 存储性能更好
|
||
- 支持灵活的数据结构
|
||
- 易于扩展
|
||
|
||
**缺点**:
|
||
- 不符合项目现有的技术栈
|
||
- 需要额外的 NoSQL 数据库基础设施
|
||
- 增加运维成本
|
||
- 与现有的数据库架构不一致
|
||
|
||
**未选择原因**: MyBatis Plus 的查询性能已经能够满足需求，使用 NoSQL 数据库会增加不必要的复杂度。
|
||
|
||
## 影响
|
||
|
||
### 系统架构影响
|
||
|
||
- **新增模块**: MetadataComponentIndexController、IMetadataComponentIndexService、MetadataComponentIndexServiceImpl、IMetadataComponentQueryService、MetadataComponentQueryServiceImpl、IMetadataComponentDetailService、MetadataComponentDetailServiceImpl、IMetadataComponentStatisticsService、MetadataComponentStatisticsServiceImpl
|
||
- **现有模块**: 复用现有的文件存储和解压处理功能
|
||
- **数据库**: 新增 datai_metadata_component_index 表，存储组件索引信息
|
||
- **API**: 新增 10 个 RESTful API 接口
|
||
|
||
### 开发流程影响
|
||
|
||
- **开发工作量**: 中等，复用现有的文件存储和解压处理代码
|
||
- **测试工作量**: 中等，需要测试索引创建、查询、详情查看、统计等功能
|
||
- **文档工作量**: 低，复用现有的文档模板
|
||
|
||
### 运维管理影响
|
||
|
||
- **部署复杂度**: 低，与现有部署流程一致
|
||
- **监控复杂度**: 低，复用现有的监控机制
|
||
- **日志复杂度**: 低，复用现有的日志机制
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
|
||
- **索引创建风险**: 索引创建失败可能导致组件查询失败
|
||
- **缓解措施**: 提供索引创建进度回调，实时反馈索引创建进度，支持索引创建重试
|
||
- **查询性能风险**: 查询性能不佳可能影响用户体验
|
||
- **缓解措施**: 使用 MyBatis Plus 的分页插件实现分页查询，使用索引优化查询性能
|
||
- **文件解析风险**: 文件解析错误可能导致索引信息不准确
|
||
- **缓解措施**: 使用成熟的文件解析库，提供文件解析错误处理，支持文件解析重试
|
||
- **统计风险**: 统计逻辑错误可能导致统计信息不准确
|
||
- **缓解措施**: 使用 MyBatis Plus 的聚合查询实现统计功能，确保统计逻辑的正确性
|
||
|
||
### 业务风险
|
||
|
||
- **索引信息不准确风险**: 索引信息不准确可能导致组件查询失败
|
||
- **缓解措施**: 提供索引创建进度回调，实时反馈索引创建进度，支持索引创建重试
|
||
- **查询结果不准确风险**: 查询结果不准确可能影响用户体验
|
||
- **缓解措施**: 使用 MyBatis Plus 的 QueryWrapper 实现多条件查询，确保查询逻辑的正确性
|
||
- **统计信息不准确风险**: 统计信息不准确可能影响决策
|
||
- **缓解措施**: 使用 MyBatis Plus 的聚合查询实现统计功能，确保统计逻辑的正确性
|
||
|
||
### 实施风险
|
||
|
||
- **依赖风险**: 依赖于 REQ-010-1, REQ-010-2, REQ-010-7
|
||
- **缓解措施**: 确保依赖的需求已经完成，避免依赖问题
|
||
|
||
## 回滚策略
|
||
|
||
如果元数据组件索引和查询功能实施后出现问题，可以采取以下回滚策略：
|
||
|
||
1. **禁用组件索引和查询功能**: 通过配置开关禁用组件索引和查询功能，回退到文件查询
|
||
2. **删除组件索引和查询相关代码**: 删除 MetadataComponentIndexController、IMetadataComponentIndexService、MetadataComponentIndexServiceImpl、IMetadataComponentQueryService、MetadataComponentQueryServiceImpl、IMetadataComponentDetailService、MetadataComponentDetailServiceImpl、IMetadataComponentStatisticsService、MetadataComponentStatisticsServiceImpl 等代码
|
||
3. **清理组件索引数据**: 清理 datai_metadata_component_index 表中的组件索引数据
|
||
4. **恢复 API**: 删除组件索引和查询相关的 API 接口
|
||
|
||
## 验收标准
|
||
|
||
### 功能验收标准
|
||
|
||
- 组件索引创建成功，支持多种元数据类型解析
|
||
- 索引信息完整准确
|
||
- 索引创建性能满足要求
|
||
- 组件查询功能正常工作
|
||
- 支持按类型查询
|
||
- 支持按名称查询
|
||
- 支持按版本查询
|
||
- 支持多条件组合查询
|
||
- 支持分页查询
|
||
- API 接口符合 RESTful 规范
|
||
- 组件详情查看成功
|
||
- 组件信息完整准确
|
||
- 支持查看组件文件内容
|
||
- 支持查看组件依赖关系
|
||
- 组件统计功能正常工作
|
||
- 统计信息准确
|
||
- 支持按类型统计
|
||
- 支持按版本统计
|
||
- 支持按组织统计
|
||
|
||
### 性能验收标准
|
||
|
||
- 组件索引创建响应时间 < 5s
|
||
- 组件查询响应时间 < 1s
|
||
- 组件详情查看响应时间 < 500ms
|
||
- 组件统计响应时间 < 1s
|
||
|
||
### 代码质量验收标准
|
||
|
||
- 代码符合项目编码规范，有清晰的注释
|
||
- 单元测试覆盖率 > 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-11.md](../requirements/REQ-010-11.md) - 元数据组件索引和查询需求文档
|
||
- [REQ-010-7.md](../requirements/REQ-010-7.md) - 文件存储和解压处理需求文档
|
||
- [0016-file-storage-and-extract.md](../decisions/adr/0016-file-storage-and-extract.md) - 文件存储和解压处理架构决策
|
||
- [file/index.md](../api-docs/file/index.md) - 文件模块 API 文档索引
|