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

---

作者：Salesforce 开发人员

作为一名 Salesforce 开发人员，我们日常工作中不可或缺的一部分就是与数据打交道。而 SOQL (Salesforce Object Query Language) 正是我们从数据库中检索数据的核心语言。虽然静态 SOQL (Static SOQL) 在大多数情况下简单高效，但总有一些场景需要我们在运行时动态地构建查询语句。这便是动态 SOQL (Dynamic SOQL) 发挥其强大作用的地方。本文将深入探讨动态 SOQL 的原理、应用场景、最佳实践以及安全注意事项，帮助您在 Apex 开发中游刃有余地驾驭这一利器。

---

背景与应用场景

在 Apex 中，我们有两种执行 SOQL 查询的方式：

静态 SOQL (Static SOQL)：这是最常见的方式，查询语句直接嵌入在方括号 `[]` 中。它的优点是代码在编译时会进行语法和字段有效性检查，可读性强，且能被开发工具很好地支持。

List<Account> accs = [SELECT Id, Name FROM Account WHERE Industry = 'Technology'];

动态 SOQL (Dynamic SOQL)：动态 SOQL 是指在运行时将一个 SOQL 查询构建为一个字符串 (String)，然后通过 `Database.query()` 或相关方法来执行。这种方式的灵活性极高，适用于查询条件在编码时无法确定的情况。

那么，我们究竟在哪些场景下需要使用动态 SOQL 呢？

• 用户自定义搜索界面：当您构建一个 Lightning Web Component 或 Visualforce 页面，允许用户选择要查询的对象、要显示的字段以及自定义的筛选条件时。这些输入在运行时才能确定，因此必须动态地拼接成一个完整的 SOQL 字符串。
• 基于配置的通用查询逻辑：假设您需要编写一个通用的服务类，该类可以根据传入的对象 API 名称和字段列表来执行查询。例如，从自定义元数据 (Custom Metadata Type) 或自定义设置 (Custom Setting) 中读取配置，然后动态生成查询。
• 处理字段集 (FieldSet)：当您希望管理员能够通过拖拽方式配置页面上应显示的字段时，可以使用字段集。在 Apex 中，您可以遍历一个字段集 (FieldSet) 的成员，动态地将这些字段名拼接进 SOQL 的 `SELECT` 子句中。
• 复杂的条件逻辑：当 `WHERE` 子句的构成依赖于一系列复杂的、互斥的业务规则时，使用多个 `if-else` 语句动态构建 `WHERE` 部分的字符串，可能比编写一个包含大量 `AND/OR` 逻辑的庞大静态 SOQL 更清晰、更易于维护。

原理说明

动态 SOQL 的核心原理非常直观：将 SOQL 查询语句作为字符串在运行时构建，然后通过 Apex 的数据库方法执行这个字符串。

实现这一过程的关键是 `Database` 类中的 `query` 方法：

List<sObject> result = Database.query(soqlQueryString);

这里的 `soqlQueryString` 就是我们动态构建的字符串。该方法会执行这个查询，并返回一个 `List` 泛型列表。由于在编译时无法知道查询返回的具体对象类型（例如是 `Account` 还是 `Contact`），因此返回类型是通用的 `sObject`。您之后需要根据业务逻辑将结果强制类型转换为具体的对象列表。

除了基本的 `Database.query()`，还有一个非常重要的概念——绑定变量 (Bind Variables)。在动态 SOQL 字符串中，可以通过在变量名前加上冒号 `:` 来引用 Apex 代码中的变量。这不仅使代码更简洁，更重要的是，它是防止 SOQL 注入 (SOQL Injection) 的关键手段。

当您在 `Database.query()` 方法中使用绑定变量时，Salesforce 平台会自动处理变量的转义，确保输入值被当作字面量而不是可执行的 SOQL 代码片段，从而极大地提升了安全性。

String objectType = 'Account';
String query = 'SELECT Id, Name FROM ' + objectType + ' WHERE Name = :nameToSearch';

在这个例子中，`objectType` 变量被直接拼接到字符串中，而 `:nameToSearch` 是一个绑定变量，它会安全地引用 Apex 上下文中的 `nameToSearch` 变量的值。

示例代码

以下示例均来自 Salesforce 官方文档，以确保其准确性和最佳实践。

示例1：基本的动态 SOQL 查询

这是一个简单的例子，演示了如何根据变量动态选择要查询的对象。

// sObjectTypeName 变量可以由方法参数、用户输入等在运行时确定
String sObjectTypeName = 'Account'; 
// 动态构建 SOQL 查询字符串
String q = 'SELECT Id, Name FROM ' + sObjectTypeName + ' LIMIT 10';

// 使用 Database.query() 执行字符串
List sobjList = Database.query(q);

// 遍历并处理结果
for(sObject s : sobjList){
    // 使用通用 sObject 的 get 方法获取字段值
    System.debug('Id: ' + s.get('Id') + ', Name: ' + s.get('Name'));
}

代码注释：

• 第 2 行：定义一个字符串变量 `sObjectTypeName`，它的值可以在运行时改变。
• 第 4 行：使用字符串拼接的方式，将对象名动态地插入到查询语句中。
• 第 7 行：调用 `Database.query()` 方法执行我们构建的字符串 `q`。返回的是一个 `List`。
• 第 10-13 行：由于返回的是 `sObject` 列表，我们无法直接通过 `s.Name` 这样的方式访问字段。必须使用通用的 `get(fieldName)` 方法来获取字段值。

---

示例2：使用绑定变量防止 SOQL 注入

在处理用户输入时，使用绑定变量至关重要。这可以防止恶意用户通过输入精心构造的字符串来篡改查询逻辑。

// 假设 aname 变量来自用户输入，例如：'Universal Containers'
String aname = 'Universal Containers';

// 错误的做法：直接拼接用户输入，存在 SOQL 注入风险
// String q = 'SELECT Id FROM Account WHERE Name = \'' + aname + '\'';

// 正确的做法：使用绑定变量
// Apex 会自动处理 aname 变量，确保它被当作一个纯粹的字符串值
String query = 'SELECT Id FROM Account WHERE Name = :aname';
List sobjList = Database.query(query);

System.debug('Found ' + sobjList.size() + ' accounts.');

代码注释：

• 第 2 行：`aname` 变量模拟了从外部（如 UI 组件）获取的用户输入。
• 第 8 行：在 `WHERE` 子句中，我们使用了 `:aname`。这告诉 Apex 运行时，去当前作用域中查找名为 `aname` 的变量，并将其值安全地绑定到查询中。即使 `aname` 的值是 `'test' OR Name != NULL` 这样的恶意字符串，它也只会被当作一个完整的字符串去匹配账户名称，而不会改变 `WHERE` 子句的逻辑结构。

---

示例3：结合字段集 (FieldSet) 的高级应用

这是一个非常实用的真实世界案例。管理员可以在 UI 上配置一个字段集，而我们的代码则动态地查询这些字段。

public List getContactsFromFieldSet() {
    // 1. 获取要查询的字段列表
    String queryFields = '';
    // 从 Contact 对象的 'MyFieldSet' 字段集中获取所有字段成员
    for (Schema.FieldSetMember f : Schema.SObjectType.Contact.fieldSets.getMap().get('MyFieldSet').getFields()) {
        if (queryFields != '') {
            queryFields += ', ';
        }
        // getFieldPath() 返回字段的 API 名称
        queryFields += f.getFieldPath();
    }

    // 2. 如果没有获取到任何字段，则抛出异常或返回空
    if (String.isBlank(queryFields)) {
        // 在实际应用中应处理此情况
        return new List();
    }

    // 3. 构建完整的动态 SOQL 字符串
    // 注意：我们将要查询的对象硬编码为 'Contact'
    String queryString = 'SELECT ' + queryFields + ' FROM Contact LIMIT 10';

    // 4. 执行查询并返回类型转换后的结果
    return (List) Database.query(queryString);
}

代码注释：

• 第 4-11 行：这段代码的核心是遍历指定的字段集 (`MyFieldSet`)。`Schema.FieldSetMember` 对象提供了有关字段集内每个字段的信息，我们使用 `getFieldPath()` 来获取其 API 名称，并用逗号拼接成 `SELECT` 子句的一部分。
• 第 20 行：我们将拼接好的字段列表、`FROM` 子句和 `LIMIT` 子句组合成一个完整的 SOQL 查询字符串。
• 第 23 行：执行查询。因为我们明确知道查询的是 `Contact` 对象，所以在返回时可以将 `List` 安全地强制类型转换为 `List`，这样调用方就可以方便地使用 `contact.FirstName` 这样的点表示法来访问字段了。

注意事项

动态 SOQL 虽然强大，但使用不当也会带来风险和性能问题。以下是必须牢记的几个要点：

1. SOQL 注入 (SOQL Injection)

这是使用动态 SOQL 时最大的安全风险。当您将用户输入直接拼接到查询字符串中时，攻击者可以通过输入恶意的 SOQL 片段来绕过安全检查或获取未授权的数据。

防御措施：

• 首选绑定变量：对于 `WHERE` 子句中的值、`LIMIT` 子句中的数字等，务必使用绑定变量。这是最简单、最安全的防御方式。
• 使用 `String.escapeSingleQuotes()`：如果必须将用户输入拼接到查询字符串中（例如，动态 `ORDER BY` 的字段名），请务必使用 `String.escapeSingleQuotes()` 方法。此方法会在字符串中的所有单引号前添加一个转义字符 `\`，防止用户输入的单引号提前闭合字符串字面量，从而破坏查询结构。

String sortField = 'Name'; // 假设这个字段名来自用户输入
// 清理输入，确保它不包含恶意的 SOQL 注入代码
String sanitizedSortField = String.escapeSingleQuotes(sortField);
String query = 'SELECT Id, Name FROM Account ORDER BY ' + sanitizedSortField;
List accounts = Database.query(query);

注意：`escapeSingleQuotes` 仅能防御一部分注入场景。对于动态选择对象名、字段名等场景，最佳实践是先将用户输入与一个预定义的、安全的“白名单”列表进行比对，确认输入是合法的对象或字段 API 名称，然后再拼接到查询中。

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

默认情况下，Apex 代码以系统模式 (System Mode) 运行，这意味着它会忽略当前用户的对象权限 (CRUD)、字段级安全 (FLS) 和共享规则 (Sharing Rules)。当您使用动态 SOQL 查询数据并将其展示给用户时，这可能会导致数据泄露，用户可能会看到他们本无权访问的记录或字段。

防御措施：

• 使用 `WITH SECURITY_ENFORCED`：这是目前推荐的最佳实践。在您的 `SELECT` 语句中添加这个子句，Salesforce 平台将在执行查询时自动为当前用户强制执行字段和对象级别的安全检查。如果用户无权访问查询中的任何一个字段或对象，查询将抛出 `QueryException` 异常。

// 即使用户无权访问 AnnualRevenue 字段，此查询在默认情况下也会成功
// String q = 'SELECT Id, Name, AnnualRevenue FROM Account';

// 使用 WITH SECURITY_ENFORCED
// 如果运行此代码的用户没有 AnnualRevenue 字段的读取权限，查询会失败并抛出异常
String q = 'SELECT Id, Name, AnnualRevenue FROM Account WITH SECURITY_ENFORCED';

try {
    List sobjList = Database.query(q);
} catch (System.QueryException e) {
    // 捕获异常并进行优雅处理，例如向用户显示错误消息
    System.debug('Query failed due to security restrictions: ' + e.getMessage());
}

注意：`WITH SECURITY_ENFORCED` 不会强制执行记录级别的共享规则。您仍然需要通过在类上声明 `with sharing` 关键字来遵循共享规则。

3. Governor 限制

动态 SOQL 查询与静态 SOQL 查询一样，受相同的 Governor 限制约束。这包括：

• 每个事务中的 SOQL 查询总数（同步 Apex 为 100 次）。
• 每个事务中检索的 SOQL 总行数（50,000 行）。

在循环中构建和执行动态 SOQL 是一个常见的反模式，它会迅速耗尽您的查询限制。请务必确保查询的批量化处理。

4. 错误处理

由于动态 SOQL 字符串是在运行时构建的，语法错误（如拼写错误的关键字、多余的逗号）无法在编译时被发现。一个格式错误的查询字符串会导致 `Database.query()` 在运行时抛出 `System.QueryException`。因此，强烈建议将所有 `Database.query()` 调用都包裹在 `try-catch` 块中，以便优雅地处理潜在的查询失败。

总结与最佳实践

动态 SOQL 是 Apex 开发工具箱中一把功能强大的瑞士军刀，它为处理不确定的、动态的数据查询需求提供了极大的灵活性。然而，能力越大，责任越大。作为专业的 Salesforce 开发人员，我们必须负责任地使用它。

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

1. 优先静态 SOQL：如果查询的结构在编译时是已知的，始终优先选择静态 SOQL。它更安全、性能更好、可读性更高。
2. 严防 SOQL 注入：对于所有来自外部（用户输入、API 请求等）的数据，都将其视为不可信的。优先使用绑定变量处理 `WHERE` 子句中的值。对于必须拼接的字符串，使用 `String.escapeSingleQuotes()` 进行清理，并尽可能通过白名单验证输入。
3. 强制安全策略：使用 `WITH SECURITY_ENFORCED` 子句来尊重用户的字段和对象权限，防止数据泄露。同时，确保您的 Apex 类根据业务需求正确声明了共享模式（`with sharing` 或 `inherited sharing`）。
4. 优雅处理异常：始终将 `Database.query()` 调用放在 `try-catch` 块中，以捕获并处理可能的 `QueryException`，避免因为一个错误的查询字符串导致整个事务失败。
5. 遵守 Governor 限制：设计您的逻辑以避免在循环中执行查询。思考如何批量化地构建您的动态查询。
6. 保持代码清晰：动态构建的字符串可能很快变得难以阅读和维护。使用辅助方法、添加注释，并将字符串的构建逻辑分解为更小的、可管理的部分，以提高代码质量。

通过遵循这些原则，您可以充分利用动态 SOQL 的灵活性，同时构建出安全、健壮且可维护的 Salesforce 应用程序。