精通 Salesforce Queueable Apex：开发者异步处理指南

十月 03, 2025

背景与应用场景

在 Salesforce 平台上，我们编写的每一行 Apex 代码都受到严格的 governor limits (总督限制) 的约束。这些限制包括 CPU 执行时间、SOQL 查询数量、DML 操作行数等。当业务逻辑变得复杂时，尤其是在触发器 (Triggers) 或复杂的 Visualforce 控制器中，我们很容易就会触碰到这些天花板，导致事务失败。

为了解决这个问题，Salesforce 提供了多种异步处理 (Asynchronous Processing) 机制，允许我们将一些长时间运行或资源密集型的任务推迟到后台执行，从而释放主线程，为用户提供更流畅的体验。传统的异步方法包括 Future 方法 (@future) 和 Batch Apex (批处理 Apex)。然而，它们各自有其局限性：

Future 方法 (@future)：简单易用，但只能接受原始数据类型 (primitive data types) 或其集合作为参数，无法传递复杂的 sObject (sObject 对象)。此外，它不返回任何 Job ID，使得监控和跟踪变得困难，也无法实现作业链式调用。
Batch Apex：功能强大，专为处理海量数据而设计，但其 `start`, `execute`, `finish` 的结构较为固定，对于不完全符合这种分批处理模式的复杂业务流，实现起来可能较为繁琐。

正是在这样的背景下，Queueable Apex (可队列化 Apex) 应运而生。它被设计为 Future 方法的增强版和替代品，同时又比 Batch Apex 更灵活，完美地填补了两者之间的空白。Queueable Apex 既拥有异步执行的优势，又克服了 Future 方法的诸多限制。

主要应用场景：

触发器中的复杂逻辑解耦：当触发器需要执行复杂的计算、数据处理或集成调用时，可以将其封装在一个 Queueable 作业中异步执行，避免因超出 governor limits 而导致记录保存失败。
发起 Web 服务调用 (Callouts)：从触发器中直接发起同步 Callout 是不被允许的。通过 Queueable Apex，我们可以轻松地将 Callout 逻辑放到后台执行，只需为类添加 `Database.AllowsCallouts` 接口即可。
作业链接 (Job Chaining)：当一个复杂的业务流程需要按顺序执行多个异步任务时，Queueable Apex 的链式调用能力就显得尤为重要。一个 Queueable 作业可以在其执行完毕后，启动下一个 Queueable 作业，形成一个任务链。
监控异步任务：与 Future 方法不同，`System.enqueueJob` 方法会返回一个 Job ID。我们可以通过这个 ID 查询 `AsyncApexJob` 对象，实时监控作业的执行状态（如排队中、处理中、已完成、失败），这对于调试和运维至关重要。

原理说明

Queueable Apex 的核心是 `Queueable` 接口。任何希望被放入执行队列的 Apex 类都必须实现这个接口。`Queueable` 接口非常简洁，只包含一个必须实现的方法：

void execute(QueueableContext context)

这个 `execute` 方法就是作业的核心逻辑所在。当 Salesforce 的异步处理器从队列中取出该作业时，就会调用这个方法。下面我们来分解其工作原理：

1. 实现 `Queueable` 接口

首先，你需要创建一个全局 (global) 或公共 (public) 的类，并声明它实现了 `Queueable` 接口。类中可以定义成员变量（属性），用于从主线程向异步作业传递数据。因为 Queueable 类会被序列化后放入队列，所以它可以支持非原始数据类型，例如 sObjects 或自定义的 Apex 对象。

public class MyQueueableJob implements Queueable { ... }

2. 定义构造函数和成员变量

通过构造函数，我们可以将需要处理的数据（如 Account 记录列表、某个特定的 ID 等）传递给 Queueable 类的实例。这些数据会作为成员变量存储在对象实例中，并在 `execute` 方法中被访问。

3. 实现 `execute` 方法

这是作业的入口点。所有的业务逻辑，如数据查询、更新、计算或调用其他服务，都应在此方法内完成。该方法接收一个 `QueueableContext` 类型的参数。`QueueableContext` 对象虽然目前功能有限，但它提供了一个非常有用的方法 `getJobId()`，可以获取当前正在执行的作业的 ID。

4. 启动作业

要将一个 Queueable 作业添加到队列中，你需要先创建该类的一个实例，然后调用 `System.enqueueJob()` 方法，并将该实例作为参数传入。此方法会立即将作业放入 Apex 作业队列，并返回一个唯一的 Job ID。

ID jobId = System.enqueueJob(new MyQueueableJob(someData));

5. 作业链接 (Job Chaining)

Queueable Apex 最强大的功能之一就是作业链接。在一个 Queueable 作业的 `execute` 方法内部，你可以实例化并启动另一个 Queueable 作业。这使得构建复杂的、分步骤的异步流程成为可能。例如，作业A负责查询和准备数据，完成后启动作业B进行处理，作业B处理完后再启动作业C进行通知。需要注意的是，作业链接有深度限制，以防止无限循环。

示例代码

以下示例代码直接来源于 Salesforce 官方文档。它演示了一个 Queueable 作业，该作业用于更新一组联系人 (Contacts) 的描述，并将这些联系人与其父级客户 (Account) 关联起来。然后，它会链接到另一个作业来处理后续任务。

// 官方文档示例：一个处理联系人并链接到下一个作业的 Queueable 类
public class AddPrimaryContact implements Queueable {
    private Contact contact;
    private String state;

    // 构造函数，用于接收需要处理的联系人记录和州份信息
    public AddPrimaryContact(Contact contact, String state) {
        this.contact = contact;
        this.state = state;
    }

    // execute 方法是 Queueable 作业的核心逻辑
    public void execute(QueueableContext context) {
        // 查询与指定州份匹配的所有客户 (Account)
        List<Account> accounts = [SELECT Id, Name, (SELECT Id, Name FROM Contacts)
                                 FROM Account WHERE BillingState = :state LIMIT 200];

        List<Contact> contactsToUpdate = new List<Contact>();
        for (Account acc : accounts) {
            // 遍历每个客户下的所有联系人
            for (Contact con : acc.Contacts) {
                // 更新联系人的描述
                con.Description = 'Primary contact for ' + acc.Name;
                contactsToUpdate.add(con);
            }
        }
        // 执行 DML 操作，批量更新联系人
        update contactsToUpdate;

        // **作业链接 (Job Chaining)**
        // 检查 governor limits，确保还有足够的堆栈深度来链接下一个作业
        // System.isQueueable() 在此处用于测试上下文，实际生产中可以根据业务逻辑判断
        if (!System.isQueueable()) {
            // 实例化并启动下一个 Queueable 作业
            // 假设我们有一个名为 SecondJob 的 Queueable 类
            // System.enqueueJob(new SecondJob()); 
            // 注意：官方原始示例中没有提供 SecondJob 的具体实现，此处仅为演示链式调用的概念
        }
    }
}

如何调用这个 Queueable 作业：

// 1. 创建一个 Contact 记录用于传递（在实际场景中，这可能是触发器中的 new 记录）
Contact newContact = new Contact(FirstName='John', LastName='Doe');
// 注意：这个 contact 对象在 AddPrimaryContact 作业中并未直接使用，
// 而是作为一个参数示例。作业的核心逻辑是基于 state 参数查询客户。

// 2. 指定州份
String state = 'CA';

// 3. 实例化 Queueable 类，并传入参数
AddPrimaryContact job = new AddPrimaryContact(newContact, state);

// 4. 将作业添加到队列，并获取 Job ID
ID jobId = System.enqueueJob(job);

// 5. (可选) 使用 jobId 查询作业状态
AsyncApexJob jobInfo = [SELECT Status, NumberOfErrors FROM AsyncApexJob WHERE Id = :jobId];
System.debug('Job Status: ' + jobInfo.Status);

注意事项

1. Governor Limits

虽然 Queueable 作业在其自己的事务中运行，拥有独立的 governor limits，但它仍然受到一些特定限制：

入队限制：在一个同步事务中，你最多只能调用 `System.enqueueJob()` 一次。在异步执行上下文（如 Batch Apex 的 `execute` 方法）中，这个限制也是存在的。
链式调用深度：从一个 Queueable 作业链接到另一个 Queueable 作业的深度是有限制的。在生产环境中，一个作业链的原始作业和它后续启动的作业总数不能超过 Salesforce 的规定（通常是有限的，比如在 Developer Edition 中是5个）。
24小时异步 Apex 执行限制：组织在24小时内可以执行的异步 Apex 作业（包括 Future, Batch, Queueable, Schedulable）的总数是有限的。
事务限制：每个 Queueable 作业的执行仍然受制于标准的 Apex 事务限制，例如 100 个 SOQL 查询、150 个 DML 调用等。

2. 错误处理

如果 Queueable 作业在执行过程中抛出未捕获的异常，整个作业将失败，并且该事务中所有未提交的 DML 操作都将被回滚。因此，在 `execute` 方法中使用 `try-catch` 块进行异常处理是至关重要的最佳实践。你可以在 `catch` 块中记录错误、发送通知邮件，或者尝试将作业重新入队（但要小心避免无限重试）。

3. 权限与共享

Queueable 作业在启动它的用户的上下文中运行。这意味着作业将遵循该用户的简档权限 (Profile permissions) 和共享规则 (Sharing rules)。如果作业需要访问特定的记录或字段，请确保执行用户拥有相应的权限。

4. Callouts

如果你的 Queueable 作业需要向外部系统发起 HTTP Callout，你的类必须同时实现 `Database.AllowsCallouts` 接口。

public class MyQueueableWithCallout implements Queueable, Database.AllowsCallouts { ... }

5. 测试

测试 Queueable 作业非常直接。你需要在测试方法中使用 `Test.startTest()` 和 `Test.stopTest()`。在这两个方法之间调用 `System.enqueueJob()`，作业并不会立即执行，而是被放入一个模拟队列。当 `Test.stopTest()` 被调用时，所有排队的异步作业都会被同步执行。这样，你就可以在 `Test.stopTest()` 之后断言 (assert) 作业执行的结果。

总结与最佳实践

Queueable Apex 是 Salesforce 异步处理工具箱中一个强大而灵活的工具，它在功能上远超 `@future` 方法，同时比 Batch Apex 更轻量、更易于实现复杂的业务流。

最佳实践总结：

优先选择 Queueable：当需要异步处理并且需要传递 sObject、监控 Job ID 或进行作业链接时，应优先选择 Queueable Apex 而不是 `@future` 方法。
保持作业单一职责：设计你的 Queueable 作业，使其专注于一个明确的任务。如果业务流程复杂，请使用作业链接将其分解为多个独立的、可管理的步骤。
健壮的错误处理：始终在 `execute` 方法中使用 `try-catch` 块。设计一个可靠的错误记录和通知机制。
注意链式调用限制：在设计作业链时，要充分考虑其深度限制，避免因超出限制而导致流程中断。对于需要处理大量独立批次数据的场景，Batch Apex 仍然是更好的选择。
进行充分的测试：编写单元测试，覆盖成功和失败的场景，并确保在使用 `Test.stopTest()` 后对作业结果进行了正确的断言。
监控 `AsyncApexJob`：对于关键的业务流程，定期查询 `AsyncApexJob` 对象来监控作业的健康状况，可以帮助你主动发现并解决问题。

通过掌握 Queueable Apex，Salesforce 开发人员可以构建出更强大、更健壮、可扩展性更高的应用程序，从而有效绕过 governor limits，提升平台性能和用户体验。

Salesforce中文网