kris/datai

Fork 0

Kris 6357f1c579 feat：提交所有模块基础搭建完成

2026-02-06 09:58:58 +08:00

13 KiB

Raw Permalink Blame History

API 文档 - SOQL 查询功能 (004-08)

元数据

需求编号: 004-08
需求名称: SOQL 查询功能
版本号: v1.0.0
创建时间: 2026-02-06
创建人: AI Assistant
模块: datai-salesforce-tooling

API 概述

SOQL 查询功能 API 提供了一组 RESTful 接口，用于执行 Salesforce Tooling API 的 SOQL 查询操作。支持执行任意 SOQL 查询、获取更多查询结果（queryMore）、查询所有结果（自动处理分页）、使用 SoqlBuilder 构建和执行查询，以及查询操作日志管理。

核心功能

执行 SOQL 查询，返回查询结果和 queryLocator
使用 queryLocator 获取更多查询结果
自动分页查询所有结果
使用 SoqlBuilder 构建和执行查询
查询操作日志管理

技术架构

Controller: ToolingSoqlQueryController
Service: IToolingSoqlQueryService / ToolingSoqlQueryServiceImpl
Connection: ToolingConnectionFactory (复用 004-01)
Builder: SoqlBuilder (复用现有工具类)

接口列表

接口 1：执行 SOQL 查询

功能描述: 执行任意 SOQL 查询语句，返回查询结果和 queryLocator。支持所有 Tooling API 对象的查询。

请求方式: POST

请求路径: /salesforce/tooling/soql/query

权限要求: tooling:soql:query

请求参数:

参数名	类型	必填	说明
queryString	String	是	SOQL 查询语句，例如 "SELECT Id, Name FROM ApexClass LIMIT 100"
source	String	否	数据源标识，默认 "source"

请求示例:

{
  "queryString": "SELECT Id, Name, Body FROM ApexClass LIMIT 100",
  "source": "source"
}

响应参数:

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	查询结果数据
data.success	Boolean	查询是否成功
data.errorCode	String	错误码（失败时返回）
data.errorMessage	String	错误信息（失败时返回）
data.queryLocator	String	查询定位器，用于获取更多结果
data.records	Array	查询结果记录列表
data.totalSize	Integer	总记录数
data.done	Boolean	是否已获取所有结果

成功响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "success": true,
    "queryLocator": "01gXXXXXXXXXXXXXXX",
    "records": [
      {
        "Id": "01pXXXXXXXXXXXXXXX",
        "Name": "MyApexClass",
        "Body": "public class MyApexClass { ... }"
      }
    ],
    "totalSize": 1,
    "done": false
  }
}

失败响应示例:

{
  "code": 500,
  "msg": "查询失败",
  "data": {
    "success": false,
    "errorCode": "TOOLING_SOQL_002",
    "errorMessage": "查询失败：无效的查询语句"
  }
}

接口 2：获取更多查询结果

功能描述: 使用 queryLocator 获取更多查询结果（queryMore）。当一次查询无法返回所有结果时，使用此接口获取后续结果。

请求方式: POST

请求路径: /salesforce/tooling/soql/queryMore

权限要求: tooling:soql:query

请求参数:

参数名	类型	必填	说明
queryLocator	String	是	查询定位器，从上一次查询结果中获取
source	String	否	数据源标识，默认 "source"

请求示例:

{
  "queryLocator": "01gXXXXXXXXXXXXXXX",
  "source": "source"
}

响应参数:

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	查询结果数据
data.success	Boolean	查询是否成功
data.errorCode	String	错误码（失败时返回）
data.errorMessage	String	错误信息（失败时返回）
data.queryLocator	String	查询定位器，用于获取更多结果
data.records	Array	查询结果记录列表
data.totalSize	Integer	总记录数
data.done	Boolean	是否已获取所有结果

成功响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "success": true,
    "queryLocator": null,
    "records": [
      {
        "Id": "01pXXXXXXXXXXXXXXX",
        "Name": "AnotherApexClass"
      }
    ],
    "totalSize": 1,
    "done": true
  }
}

失败响应示例:

{
  "code": 500,
  "msg": "查询定位器无效",
  "data": {
    "success": false,
    "errorCode": "TOOLING_SOQL_005",
    "errorMessage": "查询定位器无效或已过期"
  }
}

接口 3：查询所有结果

功能描述: 自动分页查询所有结果，合并返回完整数据列表。适用于需要获取所有记录的场景，自动处理分页逻辑。

注意: Salesforce 限制最多返回 50000 条记录，超过限制将返回错误。

请求方式: POST

请求路径: /salesforce/tooling/soql/queryAll

权限要求: tooling:soql:query

请求参数:

参数名	类型	必填	说明
queryString	String	是	SOQL 查询语句
source	String	否	数据源标识，默认 "source"

请求示例:

{
  "queryString": "SELECT Id, Name FROM ApexClass",
  "source": "source"
}

响应参数:

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	查询结果数据
data.success	Boolean	查询是否成功
data.errorCode	String	错误码（失败时返回）
data.errorMessage	String	错误信息（失败时返回）
data.records	Array	所有查询结果记录列表
data.totalSize	Integer	总记录数

成功响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "success": true,
    "records": [
      {
        "Id": "01pXXXXXXXXXXXXXXX",
        "Name": "Class1"
      },
      {
        "Id": "01pYYYYYYYYYYYYYYY",
        "Name": "Class2"
      }
    ],
    "totalSize": 2
  }
}

失败响应示例 (超过 50000 条记录限制):

{
  "code": 500,
  "msg": "查询结果超出限制",
  "data": {
    "success": false,
    "errorCode": "TOOLING_SOQL_006",
    "errorMessage": "查询结果超出 50000 条记录限制，请使用分页查询"
  }
}

接口 4：使用 SoqlBuilder 执行查询

功能描述: 使用 SoqlBuilder 构建和执行查询。适用于需要动态构建查询条件的场景，提供更灵活的查询方式。

请求方式: POST

请求路径: /salesforce/tooling/soql/queryWithBuilder

权限要求: tooling:soql:query

请求参数:

参数名	类型	必填	说明
select	String	是	SELECT 子句，例如 "Id, Name, Body"
from	String	是	FROM 子句，例如 "ApexClass"
where	String	否	WHERE 子句，例如 "Name LIKE 'My%'"
orderBy	String	否	ORDER BY 子句，例如 "Name ASC"
limit	Integer	否	LIMIT 子句，例如 100
source	String	否	数据源标识，默认 "source"

请求示例:

{
  "select": "Id, Name, Body",
  "from": "ApexClass",
  "where": "Name LIKE 'My%'",
  "orderBy": "Name ASC",
  "limit": 100,
  "source": "source"
}

响应参数:

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	查询结果数据
data.success	Boolean	查询是否成功
data.errorCode	String	错误码（失败时返回）
data.errorMessage	String	错误信息（失败时返回）
data.queryLocator	String	查询定位器
data.records	Array	查询结果记录列表
data.totalSize	Integer	总记录数
data.done	Boolean	是否已获取所有结果

成功响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "success": true,
    "queryLocator": null,
    "records": [
      {
        "Id": "01pXXXXXXXXXXXXXXX",
        "Name": "MyApexClass",
        "Body": "public class MyApexClass { ... }"
      }
    ],
    "totalSize": 1,
    "done": true
  }
}

接口 5：获取查询日志列表

功能描述: 获取 SOQL 查询操作日志列表，支持分页查询。用于审计和监控查询操作。

请求方式: GET

请求路径: /salesforce/tooling/soql/logs

权限要求: tooling:soql:log:query

请求参数 (Query 参数):

参数名	类型	必填	说明
pageNum	Integer	否	页码，默认 1
pageSize	Integer	否	每页大小，默认 10
queryType	String	否	查询类型筛选，例如 "QUERY", "QUERY_MORE", "QUERY_ALL"
success	Boolean	否	是否成功筛选
startTime	String	否	开始时间，格式：yyyy-MM-dd HH:mm:ss
endTime	String	否	结束时间，格式：yyyy-MM-dd HH:mm:ss

请求示例:

GET /salesforce/tooling/soql/logs?pageNum=1&pageSize=10&queryType=QUERY&success=true

响应参数:

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	分页数据
data.total	Long	总记录数
data.rows	Array	日志记录列表
data.rows[].id	Long	日志 ID
data.rows[].queryString	String	查询字符串
data.rows[].queryType	String	查询类型
data.rows[].executionTimeMs	Long	执行时间（毫秒）
data.rows[].resultCount	Integer	结果数量
data.rows[].success	Boolean	是否成功
data.rows[].errorMessage	String	错误信息
data.rows[].createTime	String	创建时间

成功响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 100,
    "rows": [
      {
        "id": 1,
        "queryString": "SELECT Id, Name FROM ApexClass LIMIT 100",
        "queryType": "QUERY",
        "executionTimeMs": 150,
        "resultCount": 100,
        "success": true,
        "errorMessage": null,
        "createTime": "2026-02-06 10:30:00"
      }
    ]
  }
}

错误码

错误码	错误信息	使用场景	HTTP 状态码
TOOLING_SOQL_001	Session 无效或已过期	用户未登录或 Session 过期	401
TOOLING_SOQL_002	查询失败	SOQL 查询执行失败（语法错误、对象不存在等）	500
TOOLING_SOQL_003	权限不足	用户没有执行查询的权限	403
TOOLING_SOQL_004	用户未登录	用户未登录	401
TOOLING_SOQL_005	查询定位器无效	queryLocator 无效或已过期	400
TOOLING_SOQL_006	查询结果超出限制	查询结果超过 50000 条记录限制	400

SOQL 查询限制

Salesforce SOQL 限制

最大返回记录数: 50000 条
OFFSET 上限: 2000，且必须与 LIMIT 一起使用
**不支持 SELECT ***: 必须明确指定字段或使用 FIELDS()
不支持 BETWEEN: 请使用 >= 和 <= 组合代替
不支持 JOIN: 使用关系查询（Relationship Queries）
不支持 UNION: 无法合并两个不相关的结果集

支持的运算符

=, !=, >, >=, <, <=, LIKE, IN, NOT IN, = NULL, != NULL

支持的子句

WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET

使用示例

示例 1：基本查询

curl -X POST "http://localhost:8080/salesforce/tooling/soql/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "queryString": "SELECT Id, Name FROM ApexClass LIMIT 10"
  }'

示例 2：带条件的查询

curl -X POST "http://localhost:8080/salesforce/tooling/soql/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "queryString": "SELECT Id, Name, Body FROM ApexClass WHERE Name LIKE \"My%\" ORDER BY Name ASC LIMIT 50"
  }'

示例 3：使用 SoqlBuilder

curl -X POST "http://localhost:8080/salesforce/tooling/soql/queryWithBuilder" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "select": "Id, Name, Body",
    "from": "ApexClass",
    "where": "Name LIKE \"My%\"",
    "orderBy": "Name ASC",
    "limit": 50
  }'

示例 4：分页查询所有结果

curl -X POST "http://localhost:8080/salesforce/tooling/soql/queryAll" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "queryString": "SELECT Id, Name FROM ApexTrigger"
  }'

版本历史

v1.0.0 (2026-02-06)

初始版本
实现 5 个 REST API 接口
支持执行 SOQL 查询、queryMore、queryAll、SoqlBuilder 查询、日志管理

13 KiB Raw Permalink Blame History Unescape Escape

API 文档 - SOQL 查询功能 (004-08)

元数据

API 概述

核心功能

技术架构

接口列表

接口 1：执行 SOQL 查询

接口 2：获取更多查询结果

接口 3：查询所有结果

接口 4：使用 SoqlBuilder 执行查询

接口 5：获取查询日志列表

错误码

SOQL 查询限制

Salesforce SOQL 限制

支持的运算符

支持的子句

使用示例

示例 1：基本查询

示例 2：带条件的查询

示例 3：使用 SoqlBuilder

示例 4：分页查询所有结果

相关文档

版本历史

v1.0.0 (2026-02-06)

13 KiB

Raw Permalink Blame History