datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-02-03-004-08-ADR-SOQL查询功能技术选型.md

ADR-004-08: SOQL 查询功能技术选型

状态

已接受

日期

2026-02-03

背景

SOQL 查询功能需要选择一个可靠的技术方案，满足以下要求：

1. 支持执行 SOQL 查询（executeQuery）
2. 支持获取更多查询结果（queryMore）
3. 支持查询所有结果（自动处理分页）（queryAll）
4. 支持使用 SoqlBuilder 执行查询（executeQuery(SoqlBuilder)、queryAll(SoqlBuilder)）
5. 支持所有 Tooling API 对象的查询
6. 支持复杂的查询条件、排序、分页
7. 所有操作都记录到数据库（datai_tooling_soql_query_log 表）
8. 处理 SOQL 查询的各种约束（不支持 SELECT *、BETWEEN、JOIN、UNION）
9. 查询结果最多返回 50000 条记录，OFFSET 上限为 2000
10. 查询定位器（queryLocator）有有效期限制，需要处理过期情况

决策

选择方案 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、004-07 的技术选型保持一致
7. 开发效率高：复用现有基础设施，减少重复代码，提高开发效率
8. 维护成本低：统一的技术栈和架构，降低维护成本
9. 性能优秀：异步日志记录不影响主流程性能，连接缓存提高性能
10. 审计追溯完善：所有操作都记录到数据库，支持完整的操作审计和故障排查

放弃方案 2（直接创建 ToolingConnection + 同步日志记录 + 自定义异常 + 字符串拼接 + RESTful API）的理由：

1. 重复代码：需要重复实现连接管理逻辑，与子需求 004-01 的代码重复
2. 同步日志记录：日志记录影响主流程性能
3. 自定义异常体系：与项目现有异常体系不一致，增加维护成本
4. 字符串拼接构建 SOQL 查询：容易出错，不便于维护
5. 与项目架构不一致：与子需求 004-02、004-03、004-04、004-05、004-06、004-07 的技术选型不一致

后果

正面影响

1. 开发效率高：复用子需求 004-01 的连接管理功能，减少重复代码
2. 性能优秀：异步日志记录不影响主流程性能，连接缓存提高性能
3. 维护成本低：统一的技术栈和架构，降低维护成本
4. 审计追溯完善：所有操作都记录到数据库，支持完整的操作审计和故障排查
5. 与项目架构一致：与子需求 004-02、004-03、004-04、004-05、004-06、004-07 的技术选型保持一致
6. SOQL 查询支持：使用 SoqlBuilder 构建 SOQL 查询语句，简化查询逻辑
7. RESTful API 设计：遵循 RESTful API 设计规范，接口清晰易懂
8. 统一异常处理：使用 datai-salesforce-common 模块的异常体系，统一处理各种异常情况

负面影响

1. 依赖子需求 004-01：必须等待子需求 004-01 完成后才能开始实现
2. 异步日志记录的复杂性：需要处理异步日志记录失败的情况
3. SOQL 约束处理的复杂性：需要处理 SOQL 查询的各种约束（不支持 SELECT *、BETWEEN、JOIN、UNION）
4. 查询定位器有效期处理：需要处理查询定位器（queryLocator）的有效期限制和过期情况

替代方案

方案 2：直接创建 ToolingConnection + 同步日志记录 + 自定义异常 + 字符串拼接 + RESTful API

技术选型：

• 直接创建 ToolingConnection，不依赖子需求 004-01
• 使用同步方式记录操作日志
• 自定义异常体系
• 使用字符串拼接构建 SOQL 查询
• 遵循 RESTful API 设计规范

优点：

• 独立性强：不依赖子需求 004-01，可以独立开发和测试
• 实现简单：直接创建 ToolingConnection，实现逻辑简单
• 同步日志记录：日志记录逻辑简单，不需要处理异步情况

缺点：

• 重复代码：需要重复实现连接管理逻辑，与子需求 004-01 的代码重复
• 同步日志记录：日志记录影响主流程性能
• 自定义异常体系：与项目现有异常体系不一致，增加维护成本
• 字符串拼接构建 SOQL 查询：容易出错，不便于维护
• 与项目架构不一致：与子需求 004-02、004-03、004-04、004-05、004-06、004-07 的技术选型不一致

适用场景：

• 需要快速实现 SOQL 查询功能
• 不需要与项目现有架构保持一致
• 对性能要求不高

相关文档

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