datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-01-28-004-03-ADR-开发工具功能技术选型.md

ADR-004-03: Tooling API 开发工具功能技术选型

状态

已接受

日期

2026-01-28

背景

Tooling API 开发工具功能是 Salesforce Tooling API 集成的核心功能之一，需要设计一个可靠、高效的开发工具方案。该功能需要满足以下要求：

1. 诊断和调试：支持 Apex 代码覆盖率查询、Apex 测试队列管理、Apex 日志获取
2. 查询和搜索：支持 Apex 类成员、Apex 触发器成员、Visualforce 页面成员、Visualforce 组件成员查询
3. 连接复用：复用子需求 004-01 的 ToolingConnectionFactory 获取连接
4. 操作日志记录：所有开发工具操作记录到数据库，支持审计和追溯
5. SOQL 查询支持：支持使用 SOQL 查询各种开发工具数据
6. 异常处理：统一处理各种异常情况
7. RESTful API：提供标准的 REST API 接口
8. 性能优化：异步记录日志，不影响主流程性能

决策

选择方案 1：Service + ToolingConnectionFactory + 异步日志记录，理由如下：

1. 复用现有基础设施：复用子需求 004-01 的 ToolingConnectionFactory 获取连接，避免重复实现连接管理逻辑
2. 异步日志记录：使用 CompletableFuture 异步记录操作日志，不影响主流程性能
3. 统一异常处理：使用 datai-salesforce-common 模块的异常体系，统一处理各种异常情况
4. SOQL 查询支持：使用 SoqlBuilder 构建 SOQL 查询语句，简化查询逻辑
5. 开发效率高：利用现有的基础设施，可以快速实现开发工具功能
6. 维护成本低：与项目现有架构保持一致，与 Partner API、Apex API、Metadata API 的实现方式一致
7. 性能优秀：异步日志记录不影响主流程性能，连接复用提高性能
8. 审计追溯完善：所有开发工具操作记录到数据库，便于审计和故障排查

后果

正面影响

1. 开发效率高：利用现有的 ToolingConnectionFactory 和 SoqlBuilder，可以快速实现开发工具功能
2. 代码复用率高：复用子需求 004-01 的连接管理功能，避免重复实现
3. 维护成本低：与项目现有架构保持一致，经过充分测试，稳定性高
4. 性能优秀：异步日志记录不影响主流程性能，连接复用提高性能
5. 审计追溯完善：所有开发工具操作记录到 datai_tooling_devtools_operation_log 表，便于审计和故障排查
6. 架构一致：与 datai-salesforce-tooling 模块的架构设计保持一致
7. 异常处理统一：使用统一的异常体系，便于错误处理和用户提示

负面影响

1. 依赖关系：需要依赖子需求 004-01 的 ToolingConnectionFactory，增加了子需求间的耦合度
2. 数据库依赖：需要创建数据库表存储操作日志，增加了数据库维护成本
3. 异步复杂性：异步日志记录增加了代码复杂度，需要处理异步异常

替代方案

方案 2：同步日志记录

• 技术选型：同步记录操作日志到数据库
• 优点：
  • 实现简单，代码逻辑清晰
  • 日志记录与操作原子性，便于事务管理
  • 不需要处理异步异常
• 缺点：
  • 日志记录阻塞主流程，影响性能
  • 高并发场景下数据库压力大
  • 用户体验差，操作响应时间长
• 适用场景：对性能要求不高，操作频率很低的项目

方案 3：仅记录失败日志

• 技术选型：只记录失败的元数据操作日志，成功的操作不记录
• 优点：
  • 减少数据库写入量，提高性能
  • 减少存储空间占用
  • 关注失败场景，便于故障排查
• 缺点：
  • 无法审计成功的操作
  • 无法统计操作频率和成功率
  • 不符合完整的审计要求
• 适用场景：存储空间有限，只关注失败场景的项目

方案 4：使用消息队列记录日志

• 技术选型：使用 RabbitMQ 或 Kafka 等消息队列异步记录日志
• 优点：
  • 解耦日志记录与主流程
  • 支持高并发场景
  • 支持日志的批量处理和聚合
  • 可靠性高，消息不会丢失
• 缺点：
  • 需要引入消息队列组件，增加系统复杂度
  • 需要配置和维护消息队列
  • 增加部署和运维成本
  • 日志查询需要消费消息到数据库
• 适用场景：高并发场景，需要可靠日志记录的大型项目

方案 5：文件日志记录

• 技术选型：将操作日志记录到文件，而不是数据库
• 优点：
  • 实现简单，不需要数据库表
  • 写入性能高
  • 便于日志收集和分析（如使用 ELK）
• 缺点：
  • 不便于实时查询和统计
  • 需要额外的日志收集和分析工具
  • 不符合关系型数据查询习惯
  • 日志文件管理复杂（切割、归档、清理）
• 适用场景：有完善的日志收集和分析基础设施的项目

相关文档

• 需求文档
• 设计文档
• 参考 ADR：连接管理技术选型
• 参考 ADR：元数据操作技术选型

决策记录

决策过程

1. 识别关键决策点：

   • 日志记录方式（同步 vs 异步）
   • 日志存储方式（数据库 vs 文件 vs 消息队列）
   • 日志记录范围（全部 vs 仅失败）

2. 分析方案优缺点：

   • 对比了 5 种方案的优缺点
   • 评估了方案的可行性、成本、风险、可维护性

3. 确定最终决策：

   • 选择方案 1：Service + ToolingConnectionFactory + 异步日志记录
   • 理由：复用现有基础设施、性能优秀、审计完善、与项目架构一致

4. 检查已有 ADR 记录：

   • 检查了子需求 004-01 和 004-02 的 ADR 记录
   • 确认本决策与已有 ADR 记录无冲突
   • 本决策复用了子需求 004-01 的基础设施，与 004-02 的决策保持一致

决策参与者

• AI Assistant（决策分析）

决策时间

2026-01-28