Java CompletableFuture minimalCompletionStage 限制下游控制

服务内部如果直接返回 CompletableFuture，调用方除了继续编排，还可能看到 complete、obtrudeValue 等改变完成状态的入口。更稳妥的做法是让内部保留真正的 future，对外返回 future.minimalCompletionStage()：下游仍能使用 thenApply、thenCompose、exceptionally，但不能把服务结果“抢先完成”。

官方资料：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/concurrent/CompletableFuture.html

先把下游控制权暴露的问题说清楚

一次典型故障是：订单服务内部创建 future，公共方法把它原样返回；某个调用方为了测试或超时兜底，直接调用 complete，结果真实后端响应回来时只能得到 false。问题不在异步链本身，而在返回类型把“结果消费”和“结果完成”混成了一件事。

改造前先画清三层边界：服务内部负责完成结果；业务调用方负责组合后续动作；兼容层才负责把阶段转换成完整的 CompletableFuture。这样排查时，看到异常先问“谁拥有完成权”，而不是先增加线程池或重试。

用 minimalCompletionStage 建立下游控制边界

minimalCompletionStage() 返回一个完成状态跟随原 future 的 CompletionStage 视图。它保留异步链需要的接口，却不把完整的 CompletableFuture 控制方法交给调用方。下面的工厂方法只让内部对象持有完成权：

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;

final class OrderService {
    CompletionStage loadOrder(String id) {
        CompletableFuture result = new CompletableFuture();
        // 生产代码在回调或异步任务中完成结果；完成权留在服务内部。
        fetchFromBackend(id, result);
        // 对外只暴露 CompletionStage 的编排能力。
        return result.minimalCompletionStage();
    }

    private void fetchFromBackend(String id, CompletableFuture result) {
        // 示例省略网络客户端：成功调用 complete，失败调用 completeExceptionally。
        result.complete("order:" + id);
    }
}

调用方可以继续处理数据，但接口契约不会暗示它可以决定结果：

CompletionStage stage = service.loadOrder("A-100");
CompletionStage length = stage
    // 只转换已完成的数据，不接触底层完成权。
    .thenApply(String::length)
    // 把异常转换成调用方能识别的默认值。
    .exceptionally(error -> 0);

把兼容转换和异常处理放在适配层

最小阶段并不意味着调用方永远不能拿到 CompletableFuture。官方 API 明确保留了 toCompletableFuture() 这一适配路径；工程上应把它集中在旧接口、测试适配或确实需要 join/get 的边界，而不是在业务链中到处转换。

static  CompletableFuture adapt(CompletionStage stage) {
    // 只有旧 API 需要完整 future 时才做显式适配。
    return stage.toCompletableFuture();
}

static String read(CompletionStage stage) {
    try {
        // join 抛出 CompletionException，调用方要保留其 cause。
        return stage.toCompletableFuture().join();
    } catch (java.util.concurrent.CompletionException ex) {
        // 这里把基础异常交给统一错误映射层，而不是伪造成功值。
        throw ex;
    }
}

还有一个容易误判的边界：下游拿不到 complete，不代表它获得了取消底层任务的能力。CompletableFuture 的取消本来就是一种异常完成；如果网络客户端、任务队列或数据库操作有独立取消协议，就应在服务接口里显式提供，而不是依赖阶段视图猜测。

用接口清单防止控制权回退

代码评审可以按四项检查：公共方法是否返回 CompletionStage；内部是否仍保存原始 CompletableFuture；toCompletableFuture() 是否只出现在适配层；异常处理是否记录真实 cause。若第四项测试需要人为完成结果，应让测试替换后端依赖或注入完成器，不要把生产接口改回完整 future。

这套做法适合“服务拥有结果、调用方拥有编排”的关系。如果调用方确实需要完整的生命周期控制，就应把取消、超时和关闭设计成明确的方法或协议；仅靠返回一个更强的类型，往往只是把责任边界推迟到线上。

相关问题

minimalCompletionStage 与 copy 有什么区别

前者限制返回对象按 CompletionStage 使用，后者返回一个新的 CompletableFuture 防止客户端直接完成当前对象；如果目标是缩小公共接口，优先考虑最小阶段。

什么时候可以直接返回 CompletableFuture

当调用方确实被设计为 future 的生命周期协作者，并且 complete、cancel 等操作属于公开契约时才可以；普通结果查询接口不应默认扩大这组能力。

toCompletableFuture 会复制任务吗

它是从阶段获得可用 CompletableFuture 的适配入口，不应被当成重新提交任务的命令。是否启动底层工作，仍由原异步实现决定。