datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-02-03-004-07-ADR-高级功能技术选型.md

ADR-004-07: Tooling API 高级功能技术选型

状态

已接受

日期

2026-02-03

背景

Tooling API 高级功能是 Salesforce Tooling API 集成的重要组成部分，需要设计一个可靠、高效的高级功能方案。该功能需要满足以下要求：

1. 聚合和计算查询：支持查询累积结果操作符（AccumulateResultOperator）、累积结果条件输入类型（AccumulateResultCondInputType）、聚合表达式结果列元数据（AggregateExpressionResultColumnMetadata）、聚合查询结果列元数据（AggregateQueryResultColumnMetadata）
2. 预测和预测查询：支持查询高级账户预测显示组类型（AdvAcctFrcstDisplayGroupType）、高级账户预测度量类型（AdvAcctFcstMeasureType）、高级账户预测公式类型（AdvAcctFcstFormulaType）、高级账户预测计算方法（AdvAcctFcstComputationMethod）
3. 激活和应用查询：支持查询激活 Flow 类型（ActivationFlowType）、激活功能类型（ActivationFeatureType）、激活应用类型（ActivationAppType）、ACP 状态（ACPStatus）
4. 连接管理：复用子需求 004-01 实现的 ToolingConnectionFactory，通过工厂模式获取 ToolingConnection
5. 数据库日志记录：所有高级功能操作都记录到数据库，支持操作审计和故障排查
6. 异步日志记录：使用异步方式记录日志，避免影响主操作性能
7. 异常处理机制：将 Salesforce 异常转换为自定义异常，提供友好的错误信息
8. SOQL 查询构建：使用 SoqlBuilder 构建 SOQL 查询，提高代码可读性和可维护性
9. RESTful API 设计：提供标准的 REST API 接口
10. 错误码枚举：使用 ToolingAdvancedFeaturesErrorCode 枚举定义错误码

决策

选择方案 1：Service + ToolingConnectionFactory + 异步日志记录 + 自定义异常 + SoqlBuilder + RESTful API，理由如下：

1. 复用现有基础设施：复用子需求 004-01 的 ToolingConnectionFactory 获取连接，避免重复实现连接管理逻辑
2. 异步日志记录：使用 CompletableFuture 异步记录操作日志，不影响主流程性能
3. 统一异常处理：使用 datai-salesforce-common 模块的异常体系，统一处理各种异常情况
4. SOQL 查询支持：使用 SoqlBuilder 构建 SOQL 查询语句，简化查询逻辑
5. RESTful API 设计：遵循 RESTful API 设计规范，接口清晰易懂
6. 与项目架构一致：与子需求 004-02、004-03、004-04、004-05、004-06 的技术选型保持一致

后果

正面影响

1. 开发效率高：复用子需求 004-01 的连接管理功能，减少重复代码
2. 性能优秀：异步记录操作日志，不影响主流程性能
3. 审计完善：所有操作都记录到数据库，支持操作审计和故障排查
4. 代码可维护性高：使用 SoqlBuilder 构建 SOQL 查询，代码可读性和可维护性高
5. 用户体验好：统一的异常处理，提供友好的错误信息
6. 与项目架构一致：与子需求 004-02、004-03、004-04、004-05、004-06 的技术选型保持一致，便于维护

负面影响

1. 日志可能丢失：异步日志记录可能导致日志丢失（如果应用崩溃）
2. 需要线程池管理：需要额外的线程池管理异步任务
3. 数据库表增加：需要创建 datai_tooling_advanced_features_log 表，增加数据库存储

替代方案

方案 2：Service + ToolingConnectionFactory + 同步日志记录 + 自定义异常 + SoqlBuilder + RESTful API

• 技术选型：
  • 复用 ToolingConnectionFactory 获取连接
  • 同步记录操作日志到数据库
  • 使用 datai-salesforce-common 模块的异常体系
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口
• 优点：
  • 实现简单，易于理解
  • 日志记录可靠，不会丢失
  • 与项目现有架构保持一致
• 缺点：
  • 日志记录影响主流程性能
  • 数据库故障可能导致主流程失败
  • 并发场景下性能较差
• 适用场景：
  • 日志记录是关键业务的场景
  • 性能要求不高的场景

方案 3：Service + ToolingConnectionFactory + 异步日志记录 + 自定义异常 + 原生 SOQL + RESTful API

• 技术选型：
  • 复用 ToolingConnectionFactory 获取连接
  • 使用 CompletableFuture 异步记录操作日志
  • 使用 datai-salesforce-common 模块的异常体系
  • 使用原生 SOQL 字符串拼接
  • 提供完整的 REST API 接口
• 优点：
  • 复用现有基础设施，开发效率高
  • 异步日志记录不影响主流程性能
  • 原生 SOQL 查询性能更高
• 缺点：
  • 代码可读性和可维护性差
  • 容易出现 SQL 注入风险
  • 与项目现有代码风格不一致
• 适用场景：
  • 性能要求极高的场景
  • 快速原型开发

方案 4：Service + ToolingConnectionFactory + 异步日志记录 + 自定义异常 + SoqlBuilder + RESTful API + 消息队列

• 技术选型：
  • 复用 ToolingConnectionFactory 获取连接
  • 使用消息队列（如 RabbitMQ、Kafka）异步记录操作日志
  • 使用 datai-salesforce-common 模块的异常体系
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口
• 优点：
  • 复用现有基础设施，开发效率高
  • 消息队列保证日志不丢失
  • 高可靠性，支持分布式架构
  • 解耦日志记录和主流程
• 缺点：
  • 增加系统复杂度
  • 需要额外的消息队列基础设施
  • 运维成本高
  • 开发成本高
• 适用场景：
  • 高并发场景
  • 日志记录可靠性要求极高的场景
  • 分布式架构场景

方案 5：Service + ToolingConnectionFactory + 仅记录失败日志 + 自定义异常 + SoqlBuilder + RESTful API

• 技术选型：
  • 复用 ToolingConnectionFactory 获取连接
  • 仅记录失败的操作日志到数据库
  • 使用 datai-salesforce-common 模块的异常体系
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口
• 优点：
  • 减少数据库写入量，提高性能
  • 实现简单，易于理解
  • 与项目现有架构保持一致
• 缺点：
  • 无法完整审计所有操作
  • 无法统计操作成功率
  • 无法追踪成功操作的历史记录
• 适用场景：
  • 性能要求极高的场景
  • 只需要追踪失败操作的场景

方案 6：Service + ToolingConnectionFactory + 文件日志记录 + 自定义异常 + SoqlBuilder + RESTful API

• 技术选型：
  • 复用 ToolingConnectionFactory 获取连接
  • 将操作日志写入文件（如 JSON、CSV）
  • 使用 datai-salesforce-common 模块的异常体系
  • 使用 SoqlBuilder 构建 SOQL 查询
  • 提供完整的 REST API 接口
• 优点：
  • 实现简单，不需要数据库表
  • 写入性能高
  • 便于日志收集和分析（如使用 ELK）
• 缺点：
  • 不便于实时查询和统计
  • 需要额外的日志收集和分析工具
  • 不符合关系型数据查询习惯
  • 日志文件管理复杂（切割、归档、清理）
• 适用场景：
  • 有完善的日志收集和分析基础设施的项目

相关文档

• 需求文档
• 设计文档
• 参考 ADR：连接管理技术选型
• 参考 ADR：元数据操作技术选型
• 参考 ADR：开发工具功能技术选型
• 参考 ADR：AI和智能功能技术选型
• 参考 ADR：动作和自动化功能技术选型
• 参考 ADR：访问和安全功能技术选型