精通 Salesforce 动态 Apex：开发人员的 SOQL 和 DML 指南

作为一名 Salesforce 开发人员，我们经常需要在代码的灵活性和安全性之间寻求平衡。静态的 Apex 代码在编译时进行检查，提供了强大的类型安全和性能优势。然而，在某些复杂的业务场景下，我们需要编写能够适应元数据（Metadata）变化的代码，这时 Dynamic Apex (动态 Apex) 就成了我们工具箱中不可或缺的利器。本文将深入探讨 Dynamic Apex 的核心概念，特别是动态 SOQL 和动态 DML，并结合官方示例和最佳实践，帮助您安全、高效地驾驭这一强大功能。

---

背景与应用场景

在标准的 Apex 开发中，我们通常会编写静态代码。例如，`[SELECT Id, Name FROM Account WHERE Name = 'ACME']` 这条 SOQL 查询语句，在代码编译时，Salesforce 平台就会验证 `Account` 对象和 `Id`, `Name` 字段是否存在。如果不存在，编译将直接失败。这种方式清晰、安全且易于维护。

然而，在以下场景中，静态 Apex 会显得力不从心：

• 托管包（Managed Packages）开发：当您开发一个要在不同客户组织中安装的 AppExchange 应用时，您无法预知客户是否创建了特定的自定义对象或字段。您的代码需要能够在运行时动态地发现并使用这些元数据。
- 通用框架或组件开发：设想您正在构建一个通用的 CSV 导入工具、一个动态表单生成器或一个自定义报表引擎。这些工具的核心逻辑需要是对象和字段无关的，能够处理用户在运行时选择的任何 sObject。 - 遵循字段级安全（Field-Level Security, FLS）：当需要构建一个查询，而该查询返回的字段必须严格遵守运行用户的 FLS 设置时，动态构建 SOQL 字符串是确保不查询用户无权访问字段的有效方法。 - 复杂的集成逻辑：当与外部系统集成时，如果 API 的响应结构或请求结构可能变化，使用动态 Apex 处理 sObject 会让代码更具适应性。

在这些情况下，Dynamic Apex 允许我们在运行时（Runtime）而不是编译时（Compile-time）来确定要操作的对象、字段以及查询逻辑，从而赋予了我们的应用程序前所未有的灵活性。

原理说明

Dynamic Apex 的核心在于将代码的一部分作为字符串来处理，并在运行时进行解释和执行。它主要体现在三个方面：动态 SOQL、动态 DML 以及与 Schema 类的结合使用。

Dynamic SOQL (动态 SOQL)

Dynamic SOQL 允许我们将 SOQL 查询构建为一个字符串，然后通过 `Database.query()` 方法来执行它。这与直接在方括号 `[]` 中编写静态 SOQL 查询形成对比。

静态 SOQL:

List accs = [SELECT Id, Name FROM Account];

动态 SOQL:

String soqlString = 'SELECT Id, Name FROM Account';
List sObjectList = Database.query(soqlString);

关键区别在于，`soqlString` 可以在代码运行时根据业务逻辑被任意修改和拼接，例如加入动态的 `WHERE` 条件、选择动态的字段列表等。`Database.query()` 方法的返回值是 `List`，因为在编译时，系统无法知道查询将返回哪种具体的对象类型。

Dynamic DML (动态 DML)

动态 DML 并不是指有特定的 `Database.dynamicInsert()` 方法，而是指通过 sObject 类的通用方法 `get(fieldName)` 和 `put(fieldName, value)` 来在运行时读取和设置字段值，而无需在代码中硬编码字段的 API 名称。

静态 DML 字段设置:

Account acc = new Account();
acc.Name = 'My Test Account';
acc.Phone = '123456789';
insert acc;

动态 DML 字段设置:

sObject acc = Schema.getGlobalDescribe().get('Account').newSObject();
String nameField = 'Name';
String phoneField = 'Phone';
acc.put(nameField, 'My Dynamic Account');
acc.put(phoneField, '987654321');
insert acc;

通过 `put` 方法，我们可以用一个字符串变量来指定要设置的字段，这使得我们可以编写一个通用的方法来创建或更新任何类型的 sObject 记录。

Schema Class (模式类)

单独使用动态 SOQL 和 DML 是危险的，因为它们绕过了编译时检查。如果字符串中包含无效的对象或字段名，代码将在运行时抛出异常。为了解决这个问题，Dynamic Apex 必须与 `Schema` 类紧密结合。`Schema` 类是 Apex 的元数据 API，它允许我们在运行时“描述”或“自省”（Introspect）Salesforce org 中的所有对象、字段及其属性。

通过 `Schema` 类，我们可以在执行动态操作前进行安全检查：

• 检查对象是否存在: `Schema.getGlobalDescribe().containsKey('My_Custom_Object__c')`
- 检查字段是否存在: `Schema.SObjectType.Account.fields.getMap().containsKey('My_Custom_Field__c')` - 检查用户权限: `Schema.DescribeFieldResult.isAccessible()`, `isCreateable()`, `isUpdateable()` 等。

将这三者结合，我们就能编写出既灵活又健壮的动态 Apex 代码。

---

示例代码

以下示例均来自 Salesforce 官方文档，展示了 Dynamic Apex 在实践中的应用。

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

这个例子展示了如何基于一个变量来构建一个简单的动态 SOQL 查询。

// myObject 和 myField 可以是方法参数，或者来自配置（如自定义元数据）
String myObject = 'Account';
String myField = 'Name';

// 构建 SOQL 查询字符串
// 注意：FROM 和 SELECT 后的对象和字段名是动态的
String soqlQuery = 'SELECT Id, ' + myField + ' FROM ' + myObject + ' LIMIT 10';

try {
    // 使用 Database.query() 执行动态查询
    List searchResult = Database.query(soqlQuery);
    System.debug('Found ' + searchResult.size() + ' records.');

    // 遍历结果并使用动态 get() 方法访问字段值
    for (sObject s : searchResult) {
        System.debug('Id: ' + s.get('Id') + ', ' + myField + ': ' + s.get(myField));
    }
} catch (QueryException e) {
    // 如果 SOQL 字符串有语法错误或包含无效的对象/字段，会抛出 QueryException
    System.debug('Error executing dynamic SOQL: ' + e.getMessage());
}

示例2: 结合 Schema Describe 检查 FLS 并构建动态 SOQL

这是一个更高级、更安全的实践。在构建查询之前，代码会先检查用户是否对该字段有读取权限（FLS）。这可以防止因 FLS 限制而导致查询失败，并确保我们不会向用户暴露他们无权查看的数据。

// 假设我们要查询联系人（Contact）的一些字段
List fieldsToQuery = new List{'FirstName', 'LastName', 'Email', 'Secret_Info__c'};

// 获取 Contact 对象的描述信息
Map fieldMap = Schema.SObjectType.Contact.fields.getMap();

// 用于构建 SELECT 子句的可访问字段列表
List accessibleFields = new List();

// 遍历我们想要查询的每个字段
for (String fieldName : fieldsToQuery) {
    // 检查字段是否存在并且当前用户是否有读取权限
    if (fieldMap.containsKey(fieldName.toLowerCase()) && fieldMap.get(fieldName.toLowerCase()).getDescribe().isAccessible()) {
        accessibleFields.add(fieldName);
    }
}

// 只有当至少有一个可访问字段时才执行查询
if (!accessibleFields.isEmpty()) {
    // 动态构建 SOQL 字符串
    // String.join() 是构建逗号分隔列表的安全方式
    String soql = 'SELECT ' + String.join(accessibleFields, ',') + ' FROM Contact LIMIT 10';
    
    try {
        // 执行查询
        List contacts = Database.query(soql);
        System.debug('Query successful. Records returned: ' + contacts.size());

        // 打印第一个返回的结果
        if (!contacts.isEmpty()) {
            for(String field : accessibleFields) {
                System.debug(field + ': ' + contacts[0].get(field));
            }
        }

    } catch (QueryException e) {
        System.debug('An unexpected query error occurred: ' + e.getMessage());
    }
} else {
    System.debug('No accessible fields to query for the current user.');
}

示例3: 动态创建和插入 sObject

这个例子展示了如何动态地创建一个 sObject 实例，并使用 `put()` 方法为其字段赋值，最后执行 DML 插入操作。

// 动态获取要创建的对象类型
Schema.SObjectType targetType = Schema.getGlobalDescribe().get('Lead');
if (targetType == null) {
    System.debug('The specified sObject type does not exist.');
    return;
}

// 使用 newSObject() 方法创建 sObject 实例
sObject newLead = targetType.newSObject();

// 检查用户是否有创建权限
Schema.DescribeSObjectResult describeResult = targetType.getDescribe();
if (!describeResult.isCreateable()) {
    System.debug('User does not have permission to create this object type.');
    return;
}

// 动态地为字段赋值
// 字段名和值可以来自外部系统的映射、配置文件等
Map fieldValues = new Map{
    'LastName' => 'Smith',
    'Company' => 'Dynamic Corp',
    'Status' => 'Open - Not Contacted'
};

// 遍历 Map 并使用 put() 方法填充字段
for (String fieldName : fieldValues.keySet()) {
    // 最佳实践：在 put 之前也应检查字段的可创建性 (isCreateable)
    newLead.put(fieldName, fieldValues.get(fieldName));
}

try {
    // 执行 DML insert 操作
    Database.SaveResult sr = Database.insert(newLead, false); // 使用非独占 DML 以便部分成功

    if (sr.isSuccess()) {
        System.debug('Successfully inserted Lead with Id: ' + sr.getId());
    } else {
        // 处理错误
        for (Database.Error err : sr.getErrors()) {
            System.debug('The following error has occurred.');
            System.debug(err.getStatusCode() + ': ' + err.getMessage());
            System.debug('Fields that affected this error: ' + err.getFields());
        }
    }
} catch (DmlException e) {
    System.debug('A DML error occurred: ' + e.getMessage());
}

---

注意事项

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

1. SOQL 注入 (SOQL Injection)
这是使用 Dynamic Apex 时最大的安全风险。如果查询字符串中拼接了未经处理的用户输入，恶意用户可能会构造输入来改变 SOQL 的逻辑，从而访问或篡改未经授权的数据。 解决方案：绝对不要直接拼接来自用户输入的字符串到 SOQL 查询中。如果必须这样做，请使用 `String.escapeSingleQuotes()` 方法来转义输入中的所有单引号，以防止其破坏查询结构。

// 不安全的方式
// String query = 'SELECT Id FROM Account WHERE Name = \'' + userInput + '\'';

// 安全的方式
String userInput = 'Test\' Company';
String sanitizedInput = String.escapeSingleQuotes(userInput);
String query = 'SELECT Id FROM Account WHERE Name = \'' + sanitizedInput + '\'';
List accounts = Database.query(query);

2. Governor 限制
Dynamic Apex 并不能绕过 Salesforce 的 Governor 限制。每次 `Database.query()` 调用都计为一次 SOQL 查询（每个事务限制100次）。动态 DML 语句也同样受到 DML 语句和处理行数的限制。动态代码的性能通常略低于静态代码，因为它缺少编译时优化。

3. 权限与 FLS
如前所述，动态代码在运行时才解析，因此权限问题（如用户无权访问某个对象或字段）会在运行时以异常的形式出现，而不是在编译时。这可能导致糟糕的用户体验。最佳实践是始终在使用动态 SOQL 或 DML 之前，通过 Schema Describe 方法检查对象的 `isAccessible()`、`isCreateable()`、`isUpdateable()` 和字段的 `isAccessible()` 等权限。

4. 错误处理
由于存在各种运行时风险（无效的字段名、语法错误的查询、权限不足等），所有动态 Apex 代码块都应该被包裹在 `try-catch` 块中。捕获 `QueryException`、`DmlException` 和 `SObjectException` 等特定异常，并为用户提供清晰的错误信息或执行备用逻辑。

---

总结与最佳实践

Dynamic Apex 是 Salesforce 开发人员工具箱中的一把“双刃剑”。它提供了无与伦比的灵活性，使我们能够构建可配置、可扩展且元数据感知的应用程序。然而，这种灵活性也带来了安全和运行时稳定性的挑战。

作为一名专业的 Salesforce 开发人员，我们应遵循以下最佳实践：

• 优先选择静态 Apex：如果业务逻辑在设计时是确定的，请始终使用静态 SOQL 和静态 sObject 引用。这能为您提供编译时检查、更好的性能和更易于阅读的代码。
- 仅在必要时使用动态 Apex：将其保留给那些真正需要运行时适应性的场景，如通用框架、托管包和复杂的元数据驱动逻辑。 - 安全第一：始终将防止 SOQL 注入作为首要任务，使用 `String.escapeSingleQuotes()` 清理所有变量输入。 - 先检查，后执行：在执行任何动态查询或 DML 操作之前，利用 `Schema` 类的方法来验证对象、字段的存在性以及用户的访问权限。这可以避免运行时异常，并确保代码的健壮性。 - 拥抱健壮的错误处理：使用 `try-catch` 块来优雅地处理可能发生的运行时异常，为最终用户提供明确的反馈。

通过遵循这些原则，您可以充满信心地利用 Dynamic Apex 的强大功能，同时构建出安全、可靠且可维护的 Salesforce 应用程序。