Java CompletableFuture的complete与completeExceptionally竞争

在Java并发编程中，CompletableFuture 通常用于异步任务编排。虽然大多数情况下由异步线程自动完成，但在某些特定场景（如超时控制、缓存命中或手动触发）下，我们需要手动干预任务的完成状态。

当涉及到手动干预时，complete() 和 completeExceptionally() 是两个核心方法。它们之间存在严格的竞争关系：一旦 CompletableFuture 完成成，其状态就不可变，后续的任何尝试都将失败。

以下指南将详细剖析这两者的竞争机制，并通过代码演示如何控制和使用它们。

核心原则：先到先得

CompletableFuture 的状态变更遵循“先到先得”的单次写入原则。无论任务是正常结束还是异常结束，只有第一个成功调用的完成方法生效，后续调用都会被忽略。

这意味着，如果代码逻辑中存在两个线程：一个试图调用 complete("Success")，另一个试图调用 completeExceptionally(new Error())，谁先执行，谁就决定了这个 Future 的最终命运。

为了更直观地理解状态流转，请看下面的状态机逻辑。

代码实战：模拟竞争与状态锁定

通过以下步骤，你将在本地环境中验证 complete 和 completeExceptionally 的互斥行为。

1. 准备测试环境

打开你的 Java IDE（如 IntelliJ IDEA 或 Eclipse），创建一个新的 Java 类，命名为 CompletionRaceDemo。

2. 编写核心竞争逻辑

在 main 方法中，粘贴以下代码。这段代码模拟了先正常完成、后尝试异常完成的场景。

import java.util.concurrent.CompletableFuture;

public class CompletionRaceDemo {
    public static void main(String[] args) {
        // 1. 创建一个未完成的 CompletableFuture
        CompletableFuture<String> future = new CompletableFuture<>();

        // 2. 尝试正常完成任务
        boolean successResult = future.complete("任务正常执行完成");
        System.out.println("第一次调用 complete() 是否成功: " + successResult);

        // 3. 尝试手动标记异常（模拟竞争失败的情况）
        boolean exceptionResult = future.completeExceptionally(new RuntimeException("模拟异常"));
        System.out.println("第二次调用 completeExceptionally() 是否成功: " + exceptionResult);

        // 4. 获取最终结果
        System.out.println("最终结果: " + future.join());

        // 5. 检查异常状态
        System.out.println("是否异常结束: " + future.isCompletedExceptionally());
    }
}

3. 运行并观察输出

运行上述代码，控制台将输出如下信息：

第一次调用 complete() 是否成功: true
第二次调用 completeExceptionally() 是否成功: false
最终结果: 任务正常执行完成
是否异常结束: false

4. 分析结果

观察输出结果，可以得出以下结论：

1. 锁定机制：complete() 返回 true，表示它成功地将 Future 状态从“未完成”变更为“正常完成”。
2. 后续无效：completeExceptionally() 返回 false，表示操作被拒绝，因为 Future 已经处于完成状态。
3. 结果保留：future.join() 依然返回第一次设置的值，异常信息被完全忽略。

深入对比：complete 与 completeExceptionally

为了在实际开发中正确选择，我们需要了解这两个方法的详细差异。下表列出了它们的核心特性与返回值含义。

实战应用：超时控制中的竞争

在微服务调用中，我们经常需要一个“超时”逻辑：如果远程服务在 1 秒内返回，使用正常结果；如果超时，则抛出超时异常。这是一个典型的 complete 与 completeExceptionally 竞争场景。

1. 定义超时控制方法

新建一个方法 getWithTimeout，代码如下：

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class TimeoutDemo {
    private static final ExecutorService executor = Executors.newFixedThreadPool(2);

    public static String getWithTimeout() {
        // 1. 创建一个“占位” Future，用于在两个线程间竞争
        CompletableFuture<String> resultFuture = new CompletableFuture<>();

        // 2. 启动模拟远程调用的线程
        executor.submit(() -> {
            try {
                // 模拟耗时操作（例如 500ms 成功返回）
                Thread.sleep(500);
                // 尝试正常完成
                resultFuture.complete("远程调用成功");
            } catch (InterruptedException e) {
                resultFuture.completeExceptionally(e);
            }
        });

        // 3. 启动超时监控线程
        executor.submit(() -> {
            try {
                // 等待 1 秒
                Thread.sleep(1000);
                // 1秒后如果还没结束，尝试标记为超时异常
                resultFuture.completeExceptionally(new TimeoutException("请求超时"));
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        });

        // 4. 阻塞获取结果（谁赢返回谁）
        try {
            return resultFuture.join();
        } catch (Exception e) {
            return "捕获异常: " + e.getCause().getMessage();
        }
    }

    public static void main(String[] args) {
        System.out.println(getWithTimeout());
        executor.shutdown();
    }
}

2. 调整参数测试竞争

修改代码中 Thread.sleep 的参数来模拟不同情况：

1. 模拟正常完成：

   • 将远程调用线程的 sleep 设为 500，超时线程设为 1000。
   • 运行代码，输出将是 远程调用成功。
   • 原因：complete 比 completeExceptionally 先执行。

2. 模拟超时异常：

   • 将远程调用线程的 sleep 设为 1500，超时线程设为 1000。
   • 运行代码，输出将是 捕获异常: 请求超时。
   • 原因：completeExceptionally 比 complete 先执行。

关键注意事项

在实际项目中使用这两个方法时，请务必遵守以下规则，以避免难以排查的 Bug。

1. 检查返回值
   不要忽略 complete 和 completeExceptionally 的返回值。如果返回 false，说明你的这次“干预”来得太晚了，Future 已经被其他逻辑（如异步线程本身）结束了，此时你应该放弃后续操作或记录日志。

2. 避免并发死锁
   如果在 complete 的回调逻辑（如 thenApply）中再次尝试修改同一个 Future 的状态，虽然 CompletableFuture 内部是线程安全的，但这通常意味着代码逻辑设计存在问题，应避免这种循环依赖。

3. 使用 obtrudeValue (慎用)
   Java 还提供了 obtrudeValue 和 obtrudeException 方法。与 complete 不同，这两个方法属于“强制覆盖”，即使 Future 已经完成也会强制修改结果。

   • 警告：除非你非常清楚自己在做什么（例如实现特定的重试或测试逻辑），否则绝对不要使用这两个方法，因为它会破坏其他正在等待该 Future 的线程的预期逻辑。