Salesforce 开发人员指南：深入解析动态 Apex 的强大功能与实践

九月 27, 2025

背景与应用场景

作为一名 Salesforce 开发人员，我们在日常工作中编写的大部分 Apex 代码都是“静态的”。这意味着我们在编码时就已经明确了要操作的 sObject (Salesforce 对象) 名称、字段 API 名称以及类名。编译器在保存代码时会验证这些元数据 (Metadata) 的存在性和正确性，从而提供了编译时安全检查的优势。

然而，在许多复杂的业务场景下，静态绑定的方式会限制代码的灵活性和可重用性。例如：

托管包 (Managed Package) 开发：您开发的应用程序需要安装在不同的客户组织中，而这些组织可能有自定义的对象或字段，您的代码需要在不知道这些具体名称的情况下与它们交互。

通用组件或框架：

动态查询构建器：

与外部系统集成：

为了解决这些问题，Salesforce 平台提供了 Dynamic Apex (动态 Apex)。Dynamic Apex 允许我们在运行时才确定要操作的对象、字段和类，从而编写出更加灵活、通用和可配置的代码。它将元数据的绑定从编译时 (compile-time) 推迟到了运行时 (run-time)，为开发者打开了一扇通往高级编程技术的大门。

原理说明

Dynamic Apex 的核心在于 Salesforce 提供的一系列内置类和方法，它们允许我们在代码运行时访问和操作平台的元数据。理解这些核心组件是掌握 Dynamic Apex 的关键。

1. Schema (模式) 类

Schema 类是访问 sObject 和字段元数据的入口。它像一个元数据注册表，允许您获取关于组织中所有标准和自定义对象的信息。通过 Schema 类，您可以获取一个 Map，其中键是 sObject 的名称，值是对应的 SObjectType 令牌 (token)。

2. SObjectType 与 SObjectField 令牌

SObjectType 和 SObjectField 是特殊的 Apex 类型，被称为令牌。它们不是具体的数据实例，而是对 sObject 或字段元数据的引用。您可以把它们看作是指向特定对象或字段定义的“指针”。通过这些令牌，您可以调用 getDescribe() 方法来获取详细的描述结果。

3. DescribeSObjectResult 与 DescribeFieldResult

这是 Dynamic Apex 的信息核心。当您在 SObjectType 令牌上调用 getDescribe() 方法时，会返回一个 DescribeSObjectResult 对象。这个对象包含了关于该 sObject 的所有元数据信息，例如它的名称、标签、是否可创建、是否可删除，以及它所有字段的列表。同样，在 SObjectField 令牌上调用 getDescribe() 会返回 DescribeFieldResult 对象，其中包含字段的标签、类型、长度、是否为必填等详细信息。

4. 通用 sObject 类型与 get/put 方法

Apex 有一个通用的 sObject 类型，它可以代表任何标准或自定义对象。当您在运行时才确定对象类型时，这个通用类型就显得至关重要。结合 sObject 的 get(fieldName) 和 put(fieldName, value) 方法，您可以在不知道具体字段 API 名称的情况下，动态地读取和设置字段值。这对于编写通用逻辑至关重要。

5. Database.query 方法

与静态的 [SELECT Id FROM Account] 查询不同，Database.query(stringQuery) 方法允许您传入一个字符串形式的 SOQL 查询。这个查询字符串可以在运行时根据业务逻辑动态构建，从而实现高度灵活的数据检索。

6. Type.forName() 与 Type.newInstance()

这两个方法将动态能力从数据层面扩展到了类和对象层面。Type.forName('Namespace.ClassName') 可以在运行时根据一个字符串名称获取一个类的类型定义。然后，您可以使用 Type.newInstance() 来创建这个类的一个实例，这对于实现插件化架构或动态调用不同逻辑实现非常有用。

示例代码

以下示例均来自 Salesforce 官方文档，旨在展示 Dynamic Apex 的核心用法。

示例一：动态描述 sObject 及其字段

这个例子展示了如何获取一个组织中所有 sObject 的信息，并打印出 Account 对象的所有字段及其数据类型。这是 Dynamic Apex 最基础和常见的应用。

// 获取全局描述，它包含了组织中所有 sObject 的信息
Map<String, Schema.SObjectType> schemaMap = Schema.getGlobalDescribe();

// 通过 sObject 名称（字符串）获取 Account 的 SObjectType 令牌
Schema.SObjectType accountSchema = schemaMap.get('Account');
if (accountSchema != null) {
    // 调用 getDescribe() 方法获取详细的描述结果
    Map<String, Schema.SObjectField> fieldMap = accountSchema.getDescribe().fields.getMap();

    System.debug('Fields for Account:');
    // 遍历所有字段的 Map
    for (String fieldName : fieldMap.keySet()) {
        // 获取字段的 SObjectField 令牌
        Schema.SObjectField field = fieldMap.get(fieldName);
        // 从字段的描述结果中获取其标签和类型
        Schema.DescribeFieldResult fieldDescribe = field.getDescribe();

        // 打印字段标签和其显示类型 (如 STRING, INTEGER, DATETIME)
        System.debug(fieldDescribe.getLabel() + ' (' + fieldDescribe.getType() + ')');
    }
}

示例二：使用 Database.query() 执行动态 SOQL

这个例子演示了如何根据一个对象名和一个字段名列表在运行时构建并执行 SOQL 查询。

public List<sObject> performDynamicQuery(String objectName, List<String> fieldNames) {
    // 使用 String.join 方法将字段列表拼接成用逗号分隔的字符串
    String fields = String.join(fieldNames, ',');

    // 动态构建 SOQL 查询字符串
    String queryString = 'SELECT ' + fields + ' FROM ' + objectName + ' LIMIT 10';

    try {
        // 使用 Database.query() 执行动态查询
        // 返回的是一个通用的 List
        return Database.query(queryString);
    } catch (QueryException e) {
        // 如果查询字符串有语法错误或字段不存在，会抛出异常
        System.debug('Dynamic SOQL query failed: ' + e.getMessage());
        return null;
    }
}

// 调用示例
List<String> contactFields = new List<String>{'Id', 'Name', 'Email'};
List<sObject> contacts = performDynamicQuery('Contact', contactFields);

if (contacts != null) {
    for (sObject so : contacts) {
        // 使用通用的 get() 方法来动态获取字段值
        System.debug('Contact Name: ' + so.get('Name') + ', Email: ' + so.get('Email'));
    }
}

示例三：动态检查字段级安全 (FLS)

这是一个至关重要的安全实践。在动态访问字段之前，必须检查当前用户是否有权限读取或写入该字段。

// 假设我们想动态更新 Contact 对象的 Description 字段
String objectName = 'Contact';
String fieldName = 'Description';
String recordId = '003xxxxxxxxxxxxxxx'; // 这是一个示例 ID

// 获取 Contact 对象的 SObjectType 令牌
Schema.SObjectType s = Schema.getGlobalDescribe().get(objectName);
// 获取字段的描述结果
Schema.DescribeFieldResult f = s.getDescribe().fields.getMap().get(fieldName).getDescribe();

// 检查用户是否对该字段有更新权限
if (f.isUpdateable()) {
    // 只有在权限检查通过后才执行更新操作
    Contact c = new Contact(
        Id = recordId,
        Description = 'This was updated by dynamic Apex.'
    );
    // 使用 sObject 的 put() 方法动态设置字段值
    // c.put(fieldName, 'This was updated by dynamic Apex.'); 
    // 上面这行代码与直接设置 Description 效果相同，但更具动态性
    update c;
    System.debug('Record updated successfully.');
} else {
    // 如果没有权限，则记录日志或向用户显示错误
    System.debug('User does not have permission to update the ' + fieldName + ' field on ' + objectName);
}

注意事项

虽然 Dynamic Apex 非常强大，但在使用时必须考虑以下几点，否则可能导致性能问题、安全漏洞或运行时错误。

1. Governor 限制 (Governor Limits)

Dynamic Apex 操作会消耗 Governor 限制。特别是 Schema.getGlobalDescribe() 和 getDescribe() 调用，它们属于 "SOQL Queries" 限制中的 "describe calls" 类别。在一个事务中，describe calls 的总数是有限的（通常是100次）。应避免在循环中反复调用 describe 方法。一个好的实践是在事务开始时，将需要的元数据信息查询出来并缓存在一个静态 Map 中，供后续逻辑使用。

2. 权限与安全

这是使用 Dynamic Apex 时最需要注意的一点。静态 Apex 在编译时会检查字段级安全 (Field-Level Security, FLS)，但 Dynamic Apex 不会。代码会以系统模式 (System Mode) 运行，默认忽略 FLS。因此，您必须手动检查权限。在读取字段前使用 isAccessible()，在创建前使用 isCreateable()，在更新前使用 isUpdateable()。忽略这些检查会造成严重的安全漏洞，允许用户访问或修改他们本不应接触的数据。

3. 错误处理

由于所有绑定都在运行时发生，很多在静态 Apex 中由编译器捕获的错误（如拼写错误的字段名、不存在的对象）在 Dynamic Apex 中会变成运行时异常，例如 QueryException 或 NullPointerException。因此，所有动态操作都应该被包裹在 try-catch 块中，并进行妥善的异常处理，以防止整个事务失败。

4. 性能考量

Describe 调用相对耗时。如前所述，应尽量减少 describe 调用的次数并缓存结果。此外，静态 Apex 通常比动态 Apex 执行得更快，因为它在编译时已经解析和优化。因此，原则上应优先使用静态 Apex，仅在确实需要灵活性的场景下才使用 Dynamic Apex。

总结与最佳实践

Dynamic Apex 是 Salesforce 开发人员工具箱中一件强大的工具，它使得构建高度通用、可配置和可扩展的解决方案成为可能。通过利用 Schema 类、动态 SOQL 和通用 sObject 方法，我们可以编写出能够适应不同组织元数据和业务需求的代码。

然而，强大的能力也伴随着巨大的责任。作为专业的开发人员，我们必须遵循以下最佳实践：

优先静态，按需动态：如果业务逻辑是确定的，始终优先选择静态 Apex，以获得编译时检查、更好的性能和代码可读性。
安全第一：在任何动态 DML (Data Manipulation Language) 或查询操作之前，必须使用 describe 结果中的 isAccessible(), isCreateable(), isUpdateable() 方法来强制执行 FLS。
防御性编程：始终将动态代码（特别是 Database.query() 和 sObject.get/put）放在 try-catch 块中，以优雅地处理运行时可能出现的错误。
优化限制消耗：通过缓存 describe 结果来避免在循环中重复调用，从而节约宝贵的 Governor 限制。
保持代码清晰：动态代码的可读性通常较差。添加详细的注释，解释为什么需要使用动态逻辑，以及代码的预期行为，这对未来的维护至关重要。

正确地使用 Dynamic Apex，您将能够应对更复杂的挑战，交付更具价值和适应性的 Salesforce 解决方案。

Salesforce中文网