Salesforce 开发人员深入解析动态 Apex

作为一名 Salesforce 开发人员，我经常需要在代码中处理不确定性。有时，我们需要构建的功能无法在编译时知道确切的 SObject 对象或字段，例如：创建一个通用的数据导出工具、一个可自定义的报表生成器，或者一个根据用户在 Lightning Web Component (LWC) 中的选择来动态查询和展示数据的组件。在这些场景下，标准的静态 Apex（如 `[SELECT Id, Name FROM Account]`）就显得力不从心。这时，Dynamic Apex（动态 Apex）就成为了我们手中最强大的工具之一。

背景与应用场景

在 Salesforce 开发中，我们编写的大部分 Apex 代码都是静态的。静态 Apex 指的是我们在代码中直接引用 SObject 和字段的 API 名称。例如：

Account myAccount = [SELECT Id, Name, Industry FROM Account WHERE Name = 'GenePoint'];
myAccount.Industry = 'Biotechnology';
update myAccount;

这种方式有诸多好处：

编译时检查：Salesforce 编译器会在保存代码时验证对象和字段是否存在，拼写是否正确。这能提前发现很多低级错误。
代码清晰：代码可读性强，一眼就能看出操作的对象和字段。
性能更优：通常情况下，静态 SOQL 的性能会略好于动态 SOQL。

然而，静态 Apex 的硬编码特性也限制了其灵活性。当我们需要处理以下场景时，Dynamic Apex 就派上了用场：

通用组件开发：设想一个可以展示任何标准或自定义对象列表的 LWC。用户可以选择对象（如 Account, Contact, Opportunity），然后选择要显示的字段。后台的 Apex 控制器无法预知用户会选择哪个对象，因此必须在运行时动态构建查询语句。
元数据驱动的应用：构建一个基于 Field Set 或 Custom Metadata Type（自定义元数据类型）来决定查询哪些字段的功能。配置发生变化时，无需修改和部署 Apex 代码。
复杂的查询逻辑：当 SOQL 查询的 `WHERE` 子句需要根据多个、可选的用户输入条件来动态组合时，使用字符串拼接来构建查询语句会比写一长串 `if-else` 逻辑更加简洁高效。
托管包（Managed Package）开发：在开发 AppExchange 应用时，我们无法预知客户的 Org 中会创建什么样的自定义字段或对象。Dynamic Apex 允许我们的代码适应并使用这些客户自定义的元数据。

简而言之，Dynamic Apex 赋予了我们代码在运行时“思考”和“决策”的能力，使其能够处理在编码阶段无法确定的业务逻辑和数据结构。

原理说明

Dynamic Apex 的核心并非单一功能，而是一系列 Apex 特性的组合，主要包括以下三个方面：

1. 动态 SOQL 和 SOSL

这是 Dynamic Apex 最常见的应用。与静态 SOQL 使用方括号 `[...]` 不同，动态 SOQL 使用 `Database.query(queryString)` 方法。这个方法接受一个字符串作为参数，该字符串包含完整的 SOQL 查询语句。因为查询语句是一个普通的字符串，我们可以在运行时根据需要进行拼接和修改。

例如，静态 SOQL `[SELECT Id FROM Account]` 在动态 SOQL 中就变成了 `Database.query('SELECT Id FROM Account')`。这种方式的威力在于，这个字符串可以是一个变量，在执行 `Database.query()` 之前由程序逻辑动态构建。

与此类似，动态 SOSL 使用 `Search.query(queryString)` 方法来执行在运行时构建的 SOSL 查询。

2. Schema 编程 (Schema Programming)

如果说动态 SOQL 是“执行者”，那么 Schema 类就是“情报官”。为了在运行时安全、准确地构建查询或处理数据，我们必须能够发现当前 Org 的数据模型（Schema），比如有哪些对象、每个对象有哪些字段、字段是什么类型、当前用户是否有权限访问等。这正是 Schema 命名空间下各个类的作用。

`Schema.getGlobalDescribe()`：这个方法返回一个 Map，包含了当前 Org 中所有 SObject 的名称和对应的 `SObjectType` Token。我们可以用它来获取所有可用对象的列表。
`SObjectType.getDescribe()`：通过一个 SObject 的 Token（例如 `Account.SObjectType` 或从 `getGlobalDescribe()` 中获取的 Token），调用 `getDescribe()` 方法可以获取该对象的详细描述信息，即 `Schema.DescribeSObjectResult` 对象。这个对象包含了该对象的所有元数据，如 API 名称、标签、是否可创建、是否可查询等。
`DescribeSObjectResult.fields.getMap()`：这个方法返回一个 Map，包含了该对象所有字段的名称和对应的 `SObjectField` Token。
`SObjectField.getDescribe()`：通过一个字段的 Token，调用 `getDescribe()` 方法可以获取该字段的详细描述信息，即 `Schema.DescribeFieldResult` 对象。它包含了字段的类型、长度、标签，以及最关键的权限信息，如 `isAccessible()`（可读）、`isCreateable()`（可创建）、`isUpdateable()`（可更新）。

通过组合使用这些 Schema 方法，我们可以在代码中动态地、安全地发现和使用任何 SObject 及其字段，而无需硬编码。

3. 通用 SObject 类型

当我们在运行时才能确定操作的对象类型时，就无法将查询结果直接赋给一个具体的 SObject 类型（如 `Account` 或 `Contact`）。这时，通用的 `SObject` 类型就显得至关重要。

一个 `SObject` 变量可以引用任何类型的 Salesforce 记录。我们可以使用它的 `get(fieldName)` 和 `put(fieldName, value)` 方法来动态地读取和设置字段值，其中 `fieldName` 是一个字符串。这使得我们能够编写一段代码来处理多种不同类型的 SObject 记录。

示例代码（含详细注释）

下面的示例结合了动态 SOQL 和 Schema 编程，演示了如何编写一个通用方法，该方法接受一个对象名字符串，然后查询并返回该对象的前5条记录。这个例子完美地诠释了 Dynamic Apex 的强大之处。

public class DynamicApexExample {
    /**
     * @description 一个通用的方法，用于查询任何给定SObject的前5条记录
     * @param objectName SObject的API名称，例如 'Account', 'My_Custom_Object__c'
     * @return SObject记录列表
     */
    public static List<SObject> getRecords(String objectName) {
        // 创建一个列表用于存放查询结果，使用通用的 SObject 类型
        List<SObject> resultList = new List<SObject>();

        // 1. 使用 Schema Programming 获取对象的元数据
        // Schema.getGlobalDescribe() 返回一个 Map，键是对象的小写API名称，值是SObjectType
        Map<String, Schema.SObjectType> schemaMap = Schema.getGlobalDescribe();
        Schema.SObjectType sObjectType = schemaMap.get(objectName.toLowerCase());

        // 检查对象是否存在，防止传入无效的对象名导致程序崩溃
        if (sObjectType == null) {
            System.debug('错误：找不到名为 ' + objectName + ' 的对象。');
            return resultList; // 返回空列表
        }

        // 获取对象的详细描述信息
        Schema.DescribeSObjectResult sObjectDescribe = sObjectType.getDescribe();

        // 检查当前用户是否有读取该对象的权限
        if (!sObjectDescribe.isQueryable()) {
            System.debug('错误：当前用户没有查询对象 ' + objectName + ' 的权限。');
            return resultList;
        }

        // 2. 动态构建 SOQL 查询字符串
        // 获取该对象所有字段的 Map
        Map<String, Schema.SObjectField> fieldMap = sObjectDescribe.fields.getMap();
        
        // 提取所有字段的 API 名称
        List<String> fieldAPINames = new List<String>(fieldMap.keySet());
        
        // 使用 String.join 方法将所有字段名用逗号连接起来，构建 SELECT 子句
        String fieldsToQuery = String.join(fieldAPINames, ',');

        // 拼接完整的 SOQL 查询字符串
        // 注意：这是一个简单示例。在生产环境中，应只查询必要的字段，
        // 而不是所有字段，以避免超出查询字符串长度限制和性能问题。
        String soqlQuery = 'SELECT ' + fieldsToQuery + ' FROM ' + objectName + ' LIMIT 5';
        
        System.debug('动态生成的 SOQL: ' + soqlQuery);

        // 3. 执行动态 SOQL 查询
        try {
            // 使用 Database.query() 执行字符串形式的查询
            resultList = Database.query(soqlQuery);
        } catch (QueryException e) {
            // 捕获可能发生的查询异常，例如查询字符串语法错误
            System.debug('动态 SOQL 查询失败：' + e.getMessage());
        }

        return resultList;
    }
}
// 调用示例：
// List<SObject> accounts = DynamicApexExample.getRecords('Account');
// for(SObject acc : accounts) {
//     // 使用通用的 get 方法来访问字段值
//     System.debug('Account Name: ' + acc.get('Name'));
// }

注意事项

Dynamic Apex 功能强大，但“能力越大，责任越大”。在使用时必须高度关注以下几点：

1. SOQL 注入 (SOQL Injection)

这是使用 Dynamic Apex 时最大的安全风险。如果查询字符串的一部分来自于用户输入，而你没有对输入进行适当的清理，恶意用户可能会构造特殊的输入来篡改查询逻辑，从而绕过权限检查，获取或篡改他们本无权访问的数据。绝对不要直接将未经处理的用户输入拼接到 SOQL 查询中。

防御方法：使用 `String.escapeSingleQuotes(stringToEscape)` 方法。这个方法会在字符串中的所有单引号前添加一个转义字符（\），从而防止它们被解释为 SOQL 字符串的分隔符，有效阻止 SOQL 注入攻击。

// 错误的做法 - 容易受到 SOQL 注入攻击
String userInput = 'Test\' OR Name != \'';
String unsafeQuery = 'SELECT Id, Name FROM Account WHERE Name = \'' + userInput + '\''; 
// List<sObject> results = Database.query(unsafeQuery); // 这会查询所有Account！

// 正确的做法 - 使用 escapeSingleQuotes 进行清理
String userInput = 'Test\' OR Name != \'';
String sanitizedInput = String.escapeSingleQuotes(userInput);
String safeQuery = 'SELECT Id, Name FROM Account WHERE Name = \'' + sanitizedInput + '\'';
List<sObject> results = Database.query(safeQuery);

2. 权限与字段级安全 (Field-Level Security, FLS)

默认情况下，Apex 在系统模式（System Mode）下运行，会忽略用户的对象权限和 FLS。这意味着即使用户在 UI 上看不到某个对象或字段，你的动态 SOQL 查询仍然可以访问它。这可能会导致数据泄露。因此，在执行动态操作前，必须手动检查权限。

防御方法：

查询 (SOQL)：在 SOQL 查询字符串末尾添加 `WITH SECURITY_ENFORCED` 子句。这会让查询自动强制执行当前用户的字段和对象权限，如果用户无权访问查询中的任何字段或对象，系统会抛出 `QueryException`。这是最简单、最推荐的方式。
DML 操作：在执行 `insert`, `update`, `delete` 等操作前，使用 `Schema.DescribeSObjectResult` 和 `Schema.DescribeFieldResult` 的 `isCreateable()`, `isUpdateable()`, `isDeletable()`, `isAccessible()` 等方法进行检查。

3. Governor 限制

Dynamic Apex 同样受到 Salesforce 的 Governor 限制。`Database.query()` 和静态 SOQL 查询一样，会计入每个事务中 SOQL 查询的总数（同步 Apex 中为100次）。动态 DML 操作也同样会计入 DML 语句的限制。在循环中执行 `Database.query()` 同样是绝对禁止的。因此，在使用时仍需遵循批量化等最佳实践。

4. 错误处理

动态构建的查询字符串可能存在语法错误，或者由于权限问题（如使用 `WITH SECURITY_ENFORCED`）而失败。因此，所有的 `Database.query()` 调用都应该放在 `try-catch` 块中，以优雅地处理 `QueryException` 或其他潜在的运行时异常。

总结与最佳实践

Dynamic Apex 是 Salesforce 开发工具箱中不可或缺的一部分，它提供了无与伦比的灵活性和适应性，使我们能够构建高度通用和可配置的应用程序。

何时选择 Dynamic Apex？

当需要操作的对象或字段在编译时未知时。
当应用程序的逻辑需要根据元数据配置（如 Field Sets）动态变化时。
当需要构建复杂的、条件化的查询语句时。

何时坚持使用静态 Apex？

当对象和字段是固定的、已知的。
静态 Apex 提供了编译时安全检查，能更早地发现错误，代码也更易于维护和理解。

最佳实践：

安全第一：始终使用 `String.escapeSingleQuotes()` 来清理绑定到查询字符串中的用户输入，以防止 SOQL 注入。
尊重权限：对于查询，优先使用 `WITH SECURITY_ENFORCED` 子句。对于 DML，务必在操作前使用 Schema Describe 方法检查用户的对象和字段级权限。
代码健壮性：将所有动态 SOQL/SOSL 调用包裹在 `try-catch` 块中进行可靠的错误处理。
善用 Schema：在构建查询或处理 SObject 之前，充分利用 Schema 类来动态发现对象的元数据和权限，而不是硬编码字符串。
性能考量：避免查询所有字段（`SELECT *` 的效果）。只查询你明确需要的字段，以提高性能并避免超出查询字符串长度的限制。

通过遵循这些原则，你可以安全、高效地利用 Dynamic Apex 的强大功能，构建出更加灵活、智能和强大的 Salesforce 应用。

Salesforce Einstein AI 编程实践：开发者视角下的智能预测

九月 15, 2025

阅读全文

Salesforce中文网