精通异步 Apex：Salesforce Queueable 作业全面指南

大家好，我是一名 Salesforce 开发人员。在日常的开发工作中，我们经常会遇到需要处理耗时较长或资源密集型操作的场景，例如对大量数据进行更新、调用外部系统的 API 等。如果将这些操作放在同步执行的上下文中（比如 Trigger 或 Visualforce Controller），不仅会严重影响用户体验，还极易触发 Salesforce 平台的 Governor Limits（调节器限制）。为了解决这个问题，Salesforce 提供了强大的异步处理框架，而 Queueable Apex 正是其中非常关键且灵活的一环。今天，我将以开发人员的视角，带大家深入探讨 Queueable Apex 的世界。

背景与应用场景

在 Salesforce 的多租户环境中，为了保证所有用户共享资源的公平性，平台对每一次事务（Transaction）的计算资源（如 CPU 时间、堆大小、SOQL 查询数量等）都设置了严格的限制，这就是我们熟知的 Governor Limits。当一个操作无法在同步限制内完成时，我们就必须转向异步处理。

Salesforce 提供了多种异步 Apex 方案，包括 @future 方法、Batch Apex 和 Scheduled Apex。@future 方法是最早的异步解决方案之一，它简单易用，但功能相对局限。例如，它只能接收原始数据类型（primitive data types）的参数，无法获取作业 ID 来追踪状态，也不能将作业链接起来形成一个处理链。

Queueable Apex 的出现正是为了克服 @future 方法的这些缺点。它提供了一个更强大、更灵活的框架，可以看作是 @future 方法的“超级升级版”。

典型的应用场景包括：

复杂的数据处理：当一个 DML 操作（数据操作语言）触发了一个需要对相关记录进行一系列复杂计算和更新的逻辑时，可以使用 Queueable Apex 将这部分逻辑异步化，从而快速完成前端事务，提升用户体验。

外部系统集成：

作业链（Job Chaining）：

监控异步任务：

原理说明

Queueable Apex 的核心是 `Queueable` 接口。任何一个 Apex 类只要实现了这个接口，就可以被放入 Apex 作业队列中进行异步处理。该接口非常简单，只包含一个必须实现的方法：`execute(QueueableContext context)`。

1. 实现 `Queueable` 接口

要创建一个可排队的作业，你需要定义一个类并实现 `Queueable` 接口。

public class MyQueueableClass implements Queueable {
    public void execute(QueueableContext context) {
        // 核心业务逻辑写在这里
    }
}

2. `execute` 方法

当 Apex 运行时从队列中取出你的作业并执行时，会调用 `execute` 方法。所有的核心业务逻辑，如 SOQL 查询、DML 操作或外部服务调用，都应该写在这个方法内部。该方法接收一个 `QueueableContext` 类型的参数，但目前该接口不包含任何方法，它是一个保留接口，供 Salesforce 未来扩展使用。

3. 传递数据

与 @future 方法只能接收原始数据类型不同，Queueable Apex 可以在类的构造函数中接收和处理非原始数据类型，例如 sObject 或自定义的 Apex 对象。你可以在实例化 Queueable 类时通过构造函数将所需的数据传递给成员变量，然后在 `execute` 方法中使用这些变量。

重要提示：虽然你可以传递复杂的对象，但这些对象在作业入队时会被序列化（Serialized）。这意味着 `execute` 方法中获取到的是对象状态的一个副本，而不是对原始对象的引用。

4. 提交作业

要将作业提交到队列中，你需要实例化你的 Queueable 类，然后调用 `System.enqueueJob()` 方法。

// 实例化你的类
MyQueueableClass myJob = new MyQueueableClass();
// 提交作业并获取 Job ID
ID jobId = System.enqueueJob(myJob);

这个 `jobId` 非常有用，你可以将它存储起来，后续通过 SOQL 查询 `AsyncApexJob` 对象来跟踪作业的进展。

`SELECT Status, NumberOfErrors FROM AsyncApexJob WHERE Id = :jobId`

5. 作业链 (Job Chaining)

这是 Queueable Apex 最强大的功能之一。你可以在一个 Queueable 作业的 `execute` 方法内部，调用 `System.enqueueJob()` 来启动另一个 Queueable 作业。这使得构建复杂的、分步的业务流程成为可能。

注意：为了防止失控的递归调用耗尽系统资源，Salesforce 规定在一个 `execute` 方法中，你只能调用一次 `System.enqueueJob()` 来链接下一个作业。

示例代码

下面的示例代码来自 Salesforce 官方文档，它演示了如何创建一个 Queueable 作业来处理一组客户（Account）记录，并为每个客户创建一个关联的主要联系人（Contact）。完成之后，它会链接启动第二个作业。

第一部分：创建联系人的 Queueable 作业

这个类 `AddPrimaryContact` 接收一个联系人和一个客户的 SOQL 查询字符串。在 `execute` 方法中，它查询客户，为每个客户创建一个指定的联系人，然后将更新后的客户列表插入数据库。

// AddPrimaryContact.apxc
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) {
        // 根据构造函数传入的 state 查询符合条件的客户
        List<Account> accounts = [SELECT Id, Name FROM Account WHERE BillingState = :state LIMIT 200];
        
        List<Contact> contacts = new List<Contact>();
        for (Account acc : accounts) {
            // 为每个客户创建一个新的联系人副本
            Contact newContact = contact.clone(false, false, false, false);
            newContact.AccountId = acc.Id;
            contacts.add(newContact);
        }
        // 批量插入联系人
        insert contacts;

        // ***** 作业链的关键部分 *****
        // 在当前作业完成后，启动一个新的 Queueable 作业
        System.enqueueJob(new SecondJob());
    }
}

第二部分：被链接的第二个作业

这是一个简单的示例，仅用于演示作业链功能。在实际项目中，它可能负责执行下一步的业务逻辑，比如发送通知邮件或更新相关记录。

// SecondJob.apxc
public class SecondJob implements Queueable {
    public void execute(QueueableContext context) {
        // 这是被链接的第二个作业
        // 可以在这里执行后续的数据处理、调用或其他业务逻辑
        System.debug('This is the second job in the chain.');
    }
}

第三部分：如何启动第一个作业

你可以在任何允许执行 Apex 的地方（如匿名执行窗口、其他类的方法等）来启动这个 Queueable 作业链的第一个环节。

// 在匿名执行窗口 (Anonymous Apex) 中运行
// 1. 创建一个联系人模板
Contact contactTemplate = new Contact(FirstName='Marc', LastName='Benioff');

// 2. 实例化第一个 Queueable 作业，并传入数据
// 这里我们查找所有 BillingState 为 'CA' (加利福尼亚) 的客户
AddPrimaryContact addContactJob = new AddPrimaryContact(contactTemplate, 'CA');

// 3. 将作业提交到队列，并获取作业 ID
ID jobId = System.enqueueJob(addContactJob);

// 4. (可选) 使用作业 ID 查询作业状态
System.debug('Queueable job submitted with ID: ' + jobId);

注意事项

1. Governor Limits

队列限制：在一个同步事务中，你最多可以通过 `System.enqueueJob()` 添加 50 个作业到队列中。在一个异步执行上下文（如另一个 Queueable 或 Batch Apex）中，这个限制是 1。
作业链深度：从一个非批处理的 Apex 作业链（即一个 Queueable 链接另一个）的最大堆栈深度为 2。这意味着从一个同步执行的 Apex 启动的链，在 Developer Edition 和 Trial org 中，A -> B，B 不能再链接 C。但在生产环境中此限制通常更高。请务必查阅最新的官方文档来确认你所在环境的限制。
每日异步执行限制：你的组织在 24 小时内可以执行的异步 Apex 作业（包括 @future, Queueable, Batch, Scheduled）总数是有限的，具体数量取决于你的 Salesforce 版本和用户许可。

2. 错误处理

强烈建议在 `execute` 方法中使用 `try-catch` 块来捕获和处理潜在的异常。如果一个 Queueable 作业在执行过程中抛出未被捕获的异常，整个作业将失败，其所有 DML 操作都将被回滚。如果这个作业是作业链的一部分，那么后续的作业将不会被添加到队列中，整个链条会在此中断。你应该在 `catch` 块中记录错误信息（例如，创建一个自定义的日志对象记录），并考虑设计重试机制或发送失败通知。

3. 测试 (Testing)

测试 Queueable Apex 非常直接。你需要在测试方法中，将 `System.enqueueJob()` 的调用包含在 `Test.startTest()` 和 `Test.stopTest()` 代码块之间。当 `Test.stopTest()` 执行时，Salesforce 会立即同步执行队列中的所有异步作业，这样你就可以在测试方法的后续部分使用 `System.assertEquals()` 来验证作业执行的结果是否符合预期。

@isTest
private class AddPrimaryContactTest {
    @isTest
    static void testQueueable() {
        // 1. 准备测试数据
        Contact contactTemplate = new Contact(FirstName='Test', LastName='Contact');
        List<Account> testAccounts = new List<Account>();
        for(Integer i=0; i<50; i++) {
            testAccounts.add(new Account(Name='Test Account ' + i, BillingState='CA'));
        }
        insert testAccounts;

        // 2. 开始测试异步执行
        Test.startTest();
        // 提交作业
        AddPrimaryContact testJob = new AddPrimaryContact(contactTemplate, 'CA');
        System.enqueueJob(testJob);
        // 3. 停止测试，强制执行异步作业
        Test.stopTest();

        // 4. 验证结果
        // 验证是否为 50 个客户创建了 50 个联系人
        Integer contactCount = [SELECT count() FROM Contact WHERE LastName = 'Contact'];
        System.assertEquals(50, contactCount, '50 contacts should have been created.');
        
        // 验证第二个作业是否被调用（可以通过查询 AsyncApexJob 或其他副作用来验证）
        // 例如，如果 SecondJob 创建了一条记录，我们可以在这里查询它
    }
}

4. 事务控制

每一个 Queueable 作业都在其自己的独立事务中运行。这意味着它拥有自己的一套全新的 Governor Limits，与启动它的那个事务是分开的。这正是异步处理能够处理更多数据和执行更复杂操作的关键原因。

总结与最佳实践

作为一名 Salesforce 开发人员，Queueable Apex 是你工具箱中不可或缺的利器。它在 @future 方法的简单性和 Batch Apex 的强大功能之间取得了完美的平衡，是处理中等规模数据和构建复杂业务流程的首选。

何时选择 Queueable Apex？

当你需要进行异步处理，并且需要监控作业状态时。
当你的业务逻辑需要按顺序执行多个步骤时（使用作业链）。
当你需要向异步逻辑传递 sObject 或其他复杂数据类型时。
当需要从 Trigger 发起一个异步 Callout 时，Queueable 是比 @future 更好的选择。

最佳实践：

保持幂等性 (Idempotent)：设计你的作业，使其在意外情况下被重复执行时，不会产生错误的副作用（例如重复创建记录）。
单一职责原则：让每个 Queueable 类专注于一个明确的任务。如果逻辑很复杂，应将其拆分为多个链接的 Queueable 作业，而不是把所有东西都塞进一个巨大的 `execute` 方法里。
健壮的错误处理：始终实现 `try-catch` 逻辑，并记录详细的错误信息，以便于排查问题。
避免深度嵌套：虽然作业链很强大，但要小心 Governor Limits 对链条深度的限制，避免设计出过长的处理链。
批量化处理：在 `execute` 方法内部，务必遵循 Apex 的最佳实践，对 SOQL 查询和 DML 操作进行批量化处理，避免在循环中执行这些操作。

希望这篇详细的指南能帮助你更好地理解和运用 Queueable Apex，在你的 Salesforce 项目中构建出更高效、更健壮的解决方案。

Salesforce中文网