Java CompletableFuture 怎样在阶段之间保留取消原因

在订单校验、批量查询这类异步链路里，真正难排查的不是“任务取消了”，而是下游只看到一个没有业务语义的取消异常。Java CompletableFuture.cancel() 没有 reason 参数；如果直接调用它，后续阶段最多知道任务被取消，却不知道是用户主动撤销、库存已变化，还是上游超时。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/CompletableFuture.html

一、先看清 cancel() 丢失了什么

CompletableFuture 实现了 Future 和 CompletionStage。官方 API 对 cancel(boolean) 的定义是：未完成时以 CancellationException 异常完成；mayInterruptIfRunning 也不等于强制中断底层计算，因为 CompletableFuture 本身并不直接控制产生结果的任务。

因此下面的代码只能得到一个状态信号：

CompletableFuture stage = new CompletableFuture();
// cancel 没有 reason 参数，后续只能观察到“取消”这一层语义
stage.cancel(false);

stage.handle((value, error) -> {
    // handle 会同时接收正常值和异常；这里无法知道业务取消来源
    return error == null ? value : error.getClass().getSimpleName();
});

如果这条链要把取消原因写入监控标签，直接从 cancel() 里恢复原因是不可靠的。原因必须在完成阶段之前显式放进去。

二、用带取消码的异常跨过阶段边界

取消原因通常需要稳定的 code 和可读 detail。让异常承载这两个字段，比把一段字符串拼进 message 更容易在日志、指标和重试策略中复用。

import java.util.concurrent.CancellationException;
import java.util.concurrent.CompletableFuture;

final class CancelledBy extends CancellationException {
    private final String code;
    private final String detail;

    CancelledBy(String code, String detail) {
        super(code + ": " + detail);
        this.code = code;
        this.detail = detail;
    }

    String code() { return code; }
    String detail() { return detail; }
}

static  CompletableFuture cancelled(String code, String detail) {
    CompletableFuture future = new CompletableFuture();
    // 用自定义 CancellationException 完成，原因会随异常完成状态进入后续阶段
    future.completeExceptionally(new CancelledBy(code, detail));
    return future;
}

这里没有调用 cancel()，而是把自定义异常交给 completeExceptionally()。它仍然走异常完成通道，但下游可以读取取消码。不要把用户输入直接当作 code；实际项目应限制 code 集合，detail 只用于可观测信息。

三、在 thenCompose 和 handle 中保留原始原因

阶段组合不会自动把异常变成普通结果。把异常留在异常通道，直到链路的日志、接口适配或重试决策边界再处理，通常最清晰：

static CompletableFuture loadOrder(String orderId) {
    return CompletableFuture.supplyAsync(() -> findOrder(orderId))
        .thenCompose(order -> {
            if (order == null) {
                // 业务原因在阶段内部产生，不能退化成无原因 cancel()
                return cancelled("ORDER_GONE", "订单已被删除");
            }
            return CompletableFuture.completedFuture(order);
        });
}

static Throwable unwrap(Throwable error) {
    // join/get 链路常见包装层，先去掉包装再识别自定义取消异常
    if (error instanceof java.util.concurrent.CompletionException
            && error.getCause() != null) {
        return error.getCause();
    }
    return error;
}

loadOrder("A-100").handle((value, error) -> {
    if (error == null) return value;
    Throwable cause = unwrap(error);
    if (cause instanceof CancelledBy cancelled) {
        // 这里可按 code 选择不重试、降级或返回业务提示
        recordCancel(cancelled.code(), cancelled.detail());
        return "已取消：" + cancelled.code();
    }
    throw new IllegalStateException("异步阶段失败", cause);
});

thenCompose 适合把下一个异步阶段接入原链路；handle 则是观察和收口边界。不要在每个阶段都把异常转成字符串，否则后续阶段无法区分可重试失败与业务取消。

四、按调用方需求选择实现方式

如果取消应直接终止后续阶段，并且下游已有异常处理约定，优先使用带原因异常。若 SDK 不希望调用者依赖异常类型，可以定义 Outcome，把 status、reasonCode 和 value 作为普通字段返回。无论选择哪条路，都应在一个明确边界统一记录取消码，并为重试策略保留“用户取消”和“资源超时”的区别。

相关问题

调用 cancel(false) 会中断正在运行的任务吗？

不能把它当作强制中断。它改变 CompletableFuture 的完成状态，底层任务是否停止取决于你使用的执行器和任务自身是否配合取消信号。

为什么 handle 里看到的是 CompletionException？

阶段组合和 join/get 可能增加包装层。进入业务判断前先沿着 cause 解包，但不要丢弃自定义取消异常本身。

什么时候该用 Outcome 而不是异常？

当取消是公共接口的预期分支、调用方不应依赖异常控制流时，用显式结果对象会更稳定；内部异步链路则通常异常传播更简洁。