精通 Salesforce Apex 动态 SOQL：开发者综合指南

十月 17, 2025

背景与应用场景

作为一名 Salesforce 开发人员，在我们的日常工作中，与数据打交道是不可避免的。SOQL (Salesforce Object Query Language) 是我们从 Salesforce 数据库中检索数据的核心工具。通常，我们使用静态 SOQL (Static SOQL)，它以中括号 `[]` 包裹，其结构在编译时就已经确定。这种方式的好处是安全性高、可读性强，并且编译器可以提前检查查询语句的语法错误，比如字段名或对象名拼写错误。

然而，在很多复杂的业务场景下，静态 SOQL 的局限性就显现出来了。当查询的条件、查询的字段、甚至查询的对象本身需要根据用户的输入、配置或其他运行时条件来决定时，静态 SOQL 就无能为力了。这时，动态 SOQL (Dynamic SOQL) 就派上了用场。

动态 SOQL 允许我们在运行时以字符串的形式构建 SOQL 查询语句。这种灵活性使其成为构建高度可配置和动态化应用的利器。以下是一些典型的应用场景：

1. 可自定义的搜索页面

想象一个复杂的搜索页面，用户可以动态选择要查询的对象（如 Account、Contact 或 Opportunity），选择要显示的字段，并添加多个过滤条件。在这种情况下，SOQL 语句的 `SELECT`、`FROM` 和 `WHERE` 子句都无法预先确定，必须在运行时根据用户的选择动态拼接而成。

2. 动态报表生成器

开发一个通用的报表组件，允许管理员通过配置（例如使用自定义元数据类型 (Custom Metadata Type)）来定义报表的查询逻辑。组件在运行时读取这些配置，动态生成 SOQL 查询来获取数据并展示。

3. 灵活的集成逻辑

当与外部系统集成时，外部系统可能会传递不同的查询参数。我们可以编写一个通用的 Apex 服务，接收这些参数，然后动态构建 SOQL 查询来满足不同的数据请求，而无需为每一种请求都硬编码一个静态查询。

简而言之，当你的查询逻辑无法在代码编写阶段完全确定时，动态 SOQL 就是你的最佳选择。它为我们提供了无与伦比的灵活性，但也带来了需要我们格外注意的责任，尤其是在安全和性能方面。

原理说明

动态 SOQL 的核心原理非常简单：它将一个标准的 SOQL 查询语句作为一个字符串 (String) 在 Apex 代码中构建，然后通过 `Database` 类的特定方法来执行这个字符串。

最核心的方法是 `Database.query(queryString)`。这个方法接收一个包含有效 SOQL 查询的字符串作为参数，执行查询，并返回一个 `List` 结果集。由于返回的是一个泛型的 sObject 列表，我们可以将其强制转换为具体的对象类型列表，如 `List`。

与静态 SOQL `[SELECT Id, Name FROM Account]` 在编译时就进行语法和字段权限检查不同，`Database.query()` 的执行完全在运行时进行。这意味着：

灵活性：你可以在代码的任何地方，使用任何逻辑来修改这个查询字符串，例如添加 `WHERE` 条件、更改 `ORDER BY` 字段，甚至更换 `FROM` 的对象。
风险：编译器无法帮助你检查错误。如果你的字符串拼接有误（例如，多了一个逗号，或者字段名拼写错误），程序不会在保存时报错，而是在运行时抛出一个 `QueryException` 异常。这就要求开发者必须编写更加健壮的错误处理逻辑。

除了 `Database.query()`，还有其他一些支持动态 SOQL 的方法，例如：

`Database.getQueryLocator(queryString)`: 用于需要处理大量数据（超过 50,000 条记录）的场景，通常与 Batch Apex 结合使用。它返回一个 `Database.QueryLocator` 对象，而不是将所有记录一次性加载到内存中。
`Database.countQuery(queryString)`: 用于执行一个 `COUNT()` 查询并返回匹配的记录总数（一个 `Integer`）。这比执行一个完整的 `query` 然后取 `size()` 更高效，因为它不返回实际的记录数据。

掌握动态 SOQL 的关键在于理解如何安全、有效地构建查询字符串，并处理它在运行时可能带来的各种问题。

示例代码

以下示例均来自 Salesforce 官方文档，展示了如何构建和执行一个简单的动态 SOQL 查询。

基础动态查询示例

这个例子演示了如何根据变量动态地指定查询的对象和 `WHERE` 条件。

// 定义要查询的对象名称和字段名称
String objectName = 'Account';
String fieldName = 'Name';
String filterValue = 'ACME';

// 开始构建 SOQL 查询字符串
// 注意 SELECT 和 FROM 子句后的空格，这是常见的拼接错误来源
String queryString = 'SELECT Id, Name FROM ' + objectName;

// 动态添加 WHERE 子句
// 我们将过滤值放在单引号中，因为它是字符串类型
queryString += ' WHERE ' + fieldName + ' = \'' + filterValue + '\'';

// 使用 Database.query() 方法执行动态 SOQL
List<sObject> sObjectList = Database.query(queryString);

// 将泛型的 List 转换为具体的 List
List<Account> accountList = (List<Account>)sObjectList;

// 遍历结果并输出
for (Account acc : accountList) {
    System.debug('Account Name: ' + acc.Name);
}

使用绑定变量防止 SOQL 注入

上面的例子虽然简单，但存在严重的安全漏洞：SOQL 注入 (SOQL Injection)。如果 `filterValue` 来自用户输入，恶意用户可以构造特殊输入来改变查询的逻辑。为了解决这个问题，最佳实践是使用绑定变量。注意：简单的 `Database.query()` 不支持直接的 Apex 绑定变量，但我们可以通过 `String.escapeSingleQuotes()` 进行清理，或者使用更现代、更安全的方法 `Database.queryWithBinds` 和 `Database.execute`。

下面是使用 `String.escapeSingleQuotes()` 进行安全处理的示例：

public List<Account> findAccountsByName(String accountName) {
    // 对来自用户输入的变量进行清理，防止SOQL注入
    // 这个方法会在任何单引号前添加一个转义字符 (\)
    String sanitizedName = String.escapeSingleQuotes(accountName);

    // 构建查询字符串，使用清理后的变量
    String queryString = 'SELECT Id, Name FROM Account WHERE Name = \'' + sanitizedName + '\'';

    // 执行查询
    return Database.query(queryString);
}

⚠️ 未找到官方文档支持 `Database.queryWithBinds` 的直接示例，但其概念是现代Apex开发中的标准安全实践。 它的工作方式是将查询字符串和绑定变量分离开来，由系统负责安全地将变量插入查询中，从而彻底杜绝 SOQL 注入的风险。

注意事项

使用动态 SOQL 是一把双刃剑。在享受其灵活性的同时，必须高度关注以下几点：

1. SOQL 注入 (SOQL Injection)

这是使用动态 SOQL 时最大的安全风险。当查询字符串拼接了未经处理的用户输入时，攻击者可以通过输入恶意的 SOQL 片段来绕过安全限制或篡改查询逻辑。例如，如果用户输入 `test' OR Name != '`，原始查询可能会变成 `SELECT Id FROM Account WHERE Name = 'test' OR Name != ''`，从而返回所有客户记录。 防护措施：

首选绑定变量：虽然 `Database.query()` 本身不直接支持，但如果你的逻辑允许，可以考虑其他支持绑定的方式。
必须使用 `String.escapeSingleQuotes()`: 对于任何来自用户输入并要拼接到查询字符串中的文本变量，都必须使用此方法进行转义处理。
类型转换：如果期望输入是数字或布尔值，请先将其转换为对应的类型（如 `Integer.valueOf()`），这样可以确保输入值的格式正确，从根本上防止注入。

2. 权限与安全 (Permissions & Security)

默认情况下，Apex 代码在系统模式 (System Mode)下运行，这意味着它会忽略当前用户的字段级安全性 (Field-Level Security, FLS) 和对象权限。静态 SOQL 在编译时会受此影响，但动态 SOQL 在运行时构建，更加需要开发者主动处理权限问题。 防护措施：

`WITH SECURITY_ENFORCED` 子句：这是目前推荐的最佳实践。在你的动态查询字符串中添加此子句，Salesforce 会自动为当前用户强制执行字段和对象级别的权限检查。如果用户无权访问查询中的任何字段或对象，系统会抛出一个 `QueryException`。
手动检查：在不支持 `WITH SECURITY_ENFORCED` 的旧 API 版本或复杂场景中，你需要使用 `Schema` 方法手动检查权限，例如 `Schema.sObjectType.Account.isAccessible()` 和 `Schema.sObjectType.Account.fields.Name.isAccessible()`。

3. Governor 限制 (Governor Limits)

动态 SOQL 查询和静态 SOQL 查询一样，都受 Salesforce 的 Governor 限制约束。主要包括：

每个事务的 SOQL 查询总数：同步 Apex 中为 100 个，异步为 200 个。
每个事务检索的记录总行数：50,000 条。

不要在循环中执行 `Database.query()`，这会很快耗尽你的查询限额。始终遵循批量化处理的原则。

4. 运行时错误与异常处理

由于动态 SOQL 绕过了编译时检查，任何语法错误、无效的字段名或对象名都会在运行时导致 `QueryException`。因此，必须将 `Database.query()` 调用放在 `try-catch` 块中，以便优雅地捕获和处理这些潜在的异常，向用户提供友好的错误信息，并记录详细的日志供调试使用。

总结与最佳实践

动态 SOQL 是 Salesforce 平台上一项极其强大的功能，它为开发者提供了构建复杂、灵活和高度可配置应用程序的能力。然而，强大的能力也伴随着巨大的责任。作为专业的 Salesforce 开发人员，我们必须负责任地使用它。

以下是使用动态 SOQL 的核心最佳实践总结：

优先选择静态 SOQL：如果一个查询的结构在编译时是已知的，永远优先使用静态 SOQL。它更安全、更易读、性能也更好。只有在绝对必要时才使用动态 SOQL。
严防 SOQL 注入：这是安全方面的重中之重。始终使用 `String.escapeSingleQuotes()` 清理用户输入，或者使用更安全的绑定变量机制。
强制执行安全策略：使用 `WITH SECURITY_ENFORCED` 子句来确保数据访问符合用户的权限设置。这是保护数据隐私和安全的关键一步。
拥抱异常处理：将所有动态 SOQL 调用都包裹在 `try-catch` 块中，为不可避免的运行时错误做好准备。
代码可读性：动态构建字符串可能会让代码变得难以阅读和维护。使用清晰的变量命名，添加注释，并将复杂的字符串构建逻辑封装到独立的辅助方法中。
尊重 Governor 限制：在设计解决方案时，始终考虑 Governor 限制，确保你的动态查询逻辑是高效且可扩展的。

通过遵循这些原则，你可以自信地利用动态 SOQL 的强大功能，同时构建出安全、健壮且可维护的 Salesforce 应用程序。

Salesforce中文网