Java CompletableFuture obtrudeException 强制改写结果的处理边界

排查异步缓存或补偿流程时，偶尔会遇到一个很特殊的需求：CompletableFuture 已经有结果，但后续读取必须统一暴露为失败。obtrudeException 就是为这种故障恢复场景准备的强制覆盖方法。

调用 obtrudeException 后，后续对这个 future 的 get()、join() 等读取会抛出指定异常；但已经开始或已经完成的依赖阶段可能仍保留覆盖前的结果。因此它适合隔离故障和人工恢复，不适合替代正常的异常传播。

obtrudeException 改写的到底是什么

complete 和 completeExceptionally 遵循“第一次完成生效”的规则；obtrudeException 则是有意绕过这条规则，强制设置之后读取到的异常。它不负责停止线程，也不负责中断底层 I/O，方法名中的“强制”只针对完成结果的读取行为。

用最小示例验证后续读取边界

下面的示例先写入旧结果，再强制覆盖。关键点是：obtrudeException 不会返回新的 future，而是直接改变当前对象随后被读取时的表现。

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;

public class ObtrudeExceptionDemo {
    public static void main(String[] args) {
        CompletableFuture future = new CompletableFuture();
        future.complete("old-result"); // 模拟对象已经被旧流程正常完成

        future.obtrudeException(new IllegalStateException("manual-repair"));
        // 强制改写后续读取视图，不会回收已经执行的计算线程
        try {
            future.join();
        } catch (CompletionException ex) {
            System.out.println(ex.getCause().getMessage()); // 这里读取到 manual-repair
        }
    }
}

输出中的异常原因来自覆盖动作，而不是最初的 old-result。如果代码使用 get()，还要按受检异常处理 InterruptedException 和 ExecutionException；使用 join() 则通常从 CompletionException.getCause() 取根因。

依赖阶段为什么可能看见不同结果

依赖阶段不是一个会自动回溯的查询器。若依赖阶段在覆盖前已经完成，它可能保留旧值；覆盖后新建的依赖阶段则会从当前异常状态继续传播失败。正在执行的依赖也可能沿用已经建立的完成结果，所以不能把一次覆盖理解为全链路回滚。

CompletableFuture future = new CompletableFuture();
future.complete("old"); // 先建立一个可观察的旧结果
CompletableFuture before = future.thenApply(v -> v + "-before");

future.obtrudeException(new IllegalStateException("repair"));
// 覆盖之后新建的依赖会从异常状态开始
CompletableFuture after = future.thenApply(v -> v + "-after");

System.out.println(before.join()); // 通常仍是 old-before
try {
    after.join(); // 这里会以 CompletionException 形式失败
} catch (CompletionException ex) {
    System.out.println(ex.getCause().getMessage()); // 输出 repair
}

这里的“通常”很重要：如果依赖函数本身还在执行，完成时序会影响它最终看到的状态。图中的两条分支用于理解观察边界，不应当被当成并发时序的测试证明。

什么时候可以用，怎样避免把问题扩大

把它限定在“结果已经污染，需要让后续读取立即失败”的恢复动作中更稳妥。调用前记录 future 的业务标识、原始状态和覆盖原因；调用后统一让监控、缓存和重试逻辑识别新的异常类型。不要用它来取消底层任务，也不要在正常链路中反复覆盖同一个共享 future。

• 先确认调用方读取的是同一个 future，而不是它之前派生出的副本。
• 把覆盖动作放在单一恢复入口，避免多个线程互相改写原因。
• 对已完成依赖和运行中依赖分别记录，不能只看根 future 的状态判断全链路结果。
• 如果只是首次完成时设置失败，优先使用 completeExceptionally。

常见问题

obtrudeException 会中断正在运行的任务吗？

不会。它只改写后续读取结果，底层任务是否停止取决于任务自身、执行器和取消协议。

调用后 isCompletedExceptionally 会怎样？

当前 future 会按异常完成状态观察；但这不代表每个已派生阶段都已经切换到同一个异常。

为什么不直接用 completeExceptionally？

后者遵循未完成时才能设置的语义，适合正常链路；需要覆盖已完成结果时才考虑 obtrudeException，并承担依赖阶段不一致的代价。