Java中CompletedStage.completedFuture与CompletedStage.completedStage的差异及返回CompletionStage<Void>时的选型建议

这是个很棒的问题——很多人刚接触Java 9新增的completedStage()时都会疑惑它和老牌的completedFuture()到底有啥不一样，毕竟两者看起来功能高度重叠。咱们一步步拆解：

核心差异 #

最本质的区别体现在返回实例的能力范围上：

• completedFuture()返回的是**CompletableFuture<T>**实例，它同时实现了CompletionStage<T>和Future<T>接口，还附带了CompletableFuture自身扩展的所有工具方法（比如join()、exceptionally()的重载版本、兼容allOf()/anyOf()这类静态方法）。简单说，它是个“全能型”的异步结果容器。
• completedStage()返回的是仅实现CompletionStage<T>的轻量实例——Java文档里标注的“仅支持CompletionStage接口中的方法”是实打实的限制：这个实例没有Future的get()、isDone()、cancel()等方法，也没有CompletableFuture额外的扩展能力。如果尝试把它强转成CompletableFuture，会直接抛出ClassCastException。

何时选择哪个？ #

选哪个主要取决于你对返回实例的能力需求：

• 当你需要Future接口的阻塞/取消能力，或者要使用CompletableFuture特有的扩展操作（比如自定义异步执行器的链式方法、和其他CompletableFuture组合）：果断选completedFuture()。它是CompletionStage的超集，灵活性拉满。
• 当你只是需要满足CompletionStage的契约要求，并且希望限制调用者的操作范围（比如避免他们误用阻塞方法破坏异步流程）：选completedStage()。这在设计公共API时特别有用，能缩小API的“暴露面”，降低误用风险。
• 如果不确定后续需求：优先选completedFuture()，因为它兼容CompletionStage的所有用法，后续扩展更方便；反之如果明确不需要Future的能力，用completedStage()会更严谨。

返回CompletionStage<Void>的场景选择 #

当你需要返回CompletionStage<Void>时，completedFuture(null)和completedStage(null)都能正常工作，但还是要结合场景判断：

• 若你希望调用者只能使用CompletionStage的非阻塞链式方法（比如thenRun()、whenComplete()），不想让他们调用get()/join()（哪怕调用后只会返回null，从API设计的严谨性来说）：用completedStage(null)。
• 若后续可能需要把这个实例当作CompletableFuture来组合使用，或者调用者有合法的阻塞需求：用completedFuture(null)。

额外提一句：completedStage()的实现更轻量，因为不需要维护Future相关的状态（比如取消标记），在极端性能敏感的场景下，它的开销会略低于completedFuture()——不过这个差异非常微小，大部分业务场景下可以忽略，优先考虑API设计的合理性就好。

内容的提问来源于stack exchange，提问作者cyril