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

十一月 22, 2025

大家好，我是一名 Salesforce 开发人员。在日常的 Apex 开发工作中，我们与 SOQL (Salesforce Object Query Language) 密不可分。大多数情况下，我们使用静态 SOQL，它在编译时就会进行语法检查，非常安全高效。然而，在某些复杂的业务场景下，静态 SOQL 的灵活性就显得捉襟见肘了。这时，动态 SOQL (Dynamic SOQL) 就闪亮登场了。它允许我们在运行时构建 SOQL 查询字符串，为我们提供了无与伦比的灵活性。今天，我将从开发人员的视角，深入探讨动态 SOQL 的应用、原理、最佳实践以及需要注意的“陷阱”。

背景与应用场景

首先，我们来明确一下什么时候应该考虑使用动态 SOQL。静态 SOQL，也就是我们直接写在 `[]` 方括号里的查询，是我们的首选。因为它有以下优点：

- 编译时检查：Apex 编译器会验证查询语句中的对象名、字段名是否正确，防止因拼写错误等问题导致运行时失败。

- 防止 SOQL 注入：静态查询天生就能防御 SOQL 注入 (SOQL Injection) 攻击，因为变量是作为绑定变量处理的，而不是直接拼接到查询字符串中。

- 代码可读性强：查询逻辑一目了然。

然而，现实世界的业务需求往往是多变的。以下是一些典型的、非常适合使用动态 SOQL 的场景：

1. 用户自定义搜索页面

想象一个场景，你需要构建一个高级搜索页面，用户可以动态选择要查询的对象（如 Account 或 Contact），选择要显示的字段，并添加多个可选的筛选条件。在这种情况下，查询的结构在代码编写时是完全未知的，必须在运行时根据用户的输入来动态构建。静态 SOQL 无法满足这种需求。

2. 可复用的应用逻辑

当你需要编写一个可以处理不同 sObject 类型的通用工具类或方法时。例如，一个方法需要接收一个对象名和一个字段列表作为参数，然后返回这些字段的值。动态 SOQL 可以轻松实现这样的泛型逻辑。

3. 基于元数据的查询

在某些高级应用中，查询逻辑可能依赖于 Salesforce 的元数据。例如，根据一个字段集 (FieldSet) 来动态决定查询哪些字段。由于字段集的内容可以由管理员随时配置，代码必须在运行时去获取这些元数据信息并构建查询语句。

4. 复杂的、可选的过滤条件

当一个查询有大量可选的 `WHERE` 条件时，如果用静态 SOQL，你可能需要编写多个 `if-else` 分支，每个分支对应一个查询，这会导致代码冗余且难以维护。使用动态 SOQL，你可以根据条件是否存在，逐步构建 `WHERE` 子句，使代码更加简洁。

原理说明

动态 SOQL 的核心原理非常简单：在 Apex 代码中以字符串 (String) 的形式构建一个完整的 SOQL 查询语句，然后通过 `Database.query()` 方法执行它。

这个方法的签名是 `Database.query(queryString)`，它接收一个字符串参数，该参数就是我们动态构建的 SOQL 查询语句。它的返回值与静态 SOQL 一样，是一个 `List` 集合。

虽然原理简单，但魔鬼在细节中。与静态 SOQL 最大的不同在于，动态 SOQL 的构建过程完全在我们的代码控制之下。这意味着我们获得了极大的灵活性，但同时也必须承担起确保查询语句语法正确和安全的责任。

这里最重要的一个概念就是 SOQL 注入 (SOQL Injection)。如果你的查询字符串拼接了任何来自用户输入的文本，而没有进行适当的处理，恶意用户就可能输入特定的字符来篡改你的查询逻辑。例如，他们可能绕过过滤条件，查询到本无权访问的数据。这是所有动态查询语言都面临的严重安全风险。

为了防止 SOQL 注入，Salesforce 提供了 `String.escapeSingleQuotes(string)` 方法。这个方法会对传入字符串中的所有单引号 (`'`) 进行转义（在前面加上 `\`），从而确保用户输入的内容只能被当作字符串字面量来处理，而不会破坏查询语句的结构。

示例代码

让我们来看一个来自 Salesforce 官方文档的经典示例。这个例子演示了如何根据用户提供的搜索词，动态地在一个指定的对象上进行查询。这个例子很好地结合了动态构建和安全性处理。

场景：创建一个方法，该方法接受一个对象名 (如 'Account') 和一个搜索词 (如 'Acme')，然后查询该对象 `Name` 字段包含该搜索词的记录。

public class DynamicSOQLExample {
    public static List<sObject> searchForRecords(String objectName, String searchKey) {
        // 第一步：对用户输入进行安全处理，防止 SOQL 注入。
        // 这是使用动态 SOQL 时至关重要的一步。
        // escapeSingleQuotes 方法会转义字符串中的所有单引号。
        String sanitizedSearchKey = String.escapeSingleQuotes(searchKey);

        // 第二步：动态构建 SOQL 查询字符串。
        // 我们使用变量来指定查询的对象 (FROM 子句) 和过滤条件 (WHERE 子句)。
        // 注意 LIKE 子句中的 '%' 通配符是字符串的一部分。
        String queryString = 'SELECT Id, Name FROM ' + objectName +
                             ' WHERE Name LIKE \'%' + sanitizedSearchKey + '%\'';

        // 第三步：使用 Database.query() 方法执行动态查询。
        // 这个方法会解析并执行字符串形式的 SOQL 语句。
        // 它的返回值和静态 SOQL [SELECT ... FROM ...] 是一样的。
        List<sObject> searchResult = Database.query(queryString);

        // 第四步：返回查询结果。
        return searchResult;
    }
}

如何使用这个方法：

// 调用示例：搜索名称中包含 "GenePoint" 的客户 (Account)
List<sObject> foundAccounts = DynamicSOQLExample.searchForRecords('Account', 'GenePoint');
System.debug('Found accounts: ' + foundAccounts);

// 调用示例：搜索名称中包含 "John" 的联系人 (Contact)
// 注意：Contact 对象没有 Name 字段，而是 FirstName 和 LastName。
// 为了让上面的方法适用于 Contact，需要修改查询字符串，例如查询 LastName。
// 这也体现了动态 SOQL 的灵活性，我们可以根据 objectName 进一步调整查询逻辑。
// 一个更健壮的版本可能会检查对象类型，然后查询正确的字段。
// List<sObject> foundContacts = DynamicSOQLExample.searchForRecords('Contact', 'John');
// System.debug('Found contacts: ' + foundContacts);

注意事项

动态 SOQL 是一把双刃剑。在使用它时，必须时刻警惕以下几个关键点，以确保你的应用是安全、高效和健壮的。

SOQL 注入 (SOQL Injection)

这值得我们再次强调。永远不要直接将未经处理的用户输入拼接到动态 SOQL 查询字符串中。始终使用 `String.escapeSingleQuotes()` 来清理任何将要用在 `WHERE` 子句中的字符串变量。对于非字符串类型的数据，可以通过类型转换（如 `String.valueOf(anInteger)`）来确保其安全性。

权限与字段级安全 (Permissions & Field-Level Security)

这是一个非常容易被忽视的点。静态 SOQL 在编译时会检查运行代码的用户是否对查询的字段和对象有访问权限。如果用户没有权限，代码在运行时会抛出异常。然而，动态 SOQL 默认情况下会绕过这些检查。这意味着，如果你的代码在 `without sharing` 模式下运行，一个动态查询可能会返回用户本无权查看的字段或对象的数据，这会造成严重的数据泄露风险。

为了解决这个问题，Salesforce 引入了 `WITH SECURITY_ENFORCED` 子句。你应该尽可能地在你的动态 SOQL 查询语句中加上它。它会自动为你的查询强制应用字段和对象级别的安全权限，如果用户无权访问任何被引用的字段或对象，查询将抛出 `QueryException`。

// 安全的动态查询示例
String queryString = 'SELECT Id, Name, AnnualRevenue FROM Account ' + 
                     'WHERE Name LIKE \'%' + sanitizedSearchKey + '%\' ' +
                     'WITH SECURITY_ENFORCED';
try {
    List<Account> results = Database.query(queryString);
} catch (System.QueryException e) {
    // 处理用户无权访问字段或对象的情况
    System.debug('Query failed due to security restrictions: ' + e.getMessage());
}

如果你的 Apex 版本较旧或场景不支持 `WITH SECURITY_ENFORCED`，则必须在执行查询前，手动使用 `Schema` 类的描述方法（如 `sObjectType.getDescribe().isAccessible()` 和 `SObjectField.getDescribe().isAccessible()`）来检查权限。

Governor 限制 (Governor Limits)

动态 SOQL 和静态 SOQL 共享相同的 Governor 限制。每次调用 `Database.query()` 都会计入当前事务的 SOQL 查询总数（同步 Apex 中为 100 次）。动态构建字符串本身带来的性能开销通常可以忽略不计，但你仍然需要确保你的逻辑不会在循环中执行 SOQL 查询，并且查询本身是高效的。

可维护性与代码可读性

复杂的字符串拼接会使代码变得难以阅读和调试。当查询逻辑变得复杂时，考虑使用辅助方法或者构建者模式 (Builder Pattern) 来封装查询字符串的构建过程，使主逻辑更加清晰。同时，添加充足的注释来解释为什么需要使用动态 SOQL 以及查询的构建逻辑。

总结与最佳实践

动态 SOQL 是 Apex 开发工具箱中一个强大而必要的工具，它为处理不确定的、动态的查询需求提供了解决方案。然而，强大的能力也伴随着巨大的责任。

作为一名专业的 Salesforce 开发人员，我总结了以下几点最佳实践：

- 优先使用静态 SOQL：当查询的结构是固定的，请始终选择静态 SOQL。它的安全性、可读性和编译时检查是无与伦比的。

- 安全第一：在使用动态 SOQL 时，把安全放在首位。对所有外部输入（尤其是用户输入）使用 `String.escapeSingleQuotes()` 进行清理，以彻底杜绝 SOQL 注入的风险。

- 强制执行权限：始终在你的查询中包含 `WITH SECURITY_ENFORCED` 子句，以确保你的代码遵守 Salesforce 的共享模型和字段级安全设置。这是构建可信赖应用的基础。

- 编写清晰的代码：将复杂的查询构建逻辑封装到独立的、命名良好的方法中。使用注释来解释你的动态查询为何是必要的，以及它的工作原理。

- 考虑性能：即使是动态构建的查询，也要确保它们是“可选的” (selective)。这意味着 `WHERE` 子句应该尽可能地利用索引字段，以避免全表扫描，特别是在处理大量数据时。

掌握了动态 SOQL，你将能够构建更加灵活和强大的 Salesforce 应用。但请务必牢记这些原则和实践，确保你的代码不仅功能强大，而且安全、高效、易于维护。

Salesforce中文网