如何在Quarkus/Mutiny响应式REST GET端点中调用CompletionStage/CompletableFuture API

Quarkus/Mutiny 内置了对 JDK CompletionStage/CompletableFuture API 的原生桥接能力，不需要手动封装回调逻辑、也不需要额外做阻塞适配，即可完成和现有异步服务的对接。

核心实现方式 #

直接通过 Mutiny 提供的 Uni.createFrom().completionStage() 方法，将任意 CompletionStage 实例转换为响应式链路支持的 Uni 类型，完全匹配 Quarkus 响应式 REST 端点的返回值要求，示例代码如下：

// 示例：待对接的第三方异步服务，返回CompletionStage/CompletableFuture
public interface LegacyAsyncService {
    CompletionStage<User> fetchUserById(Long userId);
}

// Quarkus 响应式REST GET端点
@Path("/users")
public class UserEndpoint {
    @Inject
    LegacyAsyncService legacyService;

    @GET
    @Path("/{id}")
    public Uni<User> getUser(@PathParam("id") Long userId) {
        // 直接桥接CompletionStage到Mutiny Uni，无需手动处理回调、异常传递逻辑
        return Uni.createFrom().completionStage(
            legacyService.fetchUserById(userId)
        );
    }
}

关键落地注意事项 #

• 避免提前阻塞取结果：不要在构建Uni的阶段就调用get()、join()等方法从CompletionStage中强行取返回值，这类操作会直接占用事件循环线程，破坏响应式架构的非阻塞优势，正确流程是把整个CompletionStage实例直接传入桥接方法，全程保持异步流转。
• 阻塞逻辑的线程隔离：如果对接的CompletionStage实现内部存在同步阻塞IO逻辑，需要通过emitOn()将执行流程切换到Quarkus的专用阻塞线程池，避免阻塞Vert.x的事件循环：

  @Inject
  Vertx vertx;
  
  public Uni<User> getUserWithBlockingSupport(Long userId) {
      return Uni.createFrom().completionStage(
              legacyService.fetchUserById(userId)
          )
          // 切换到专用工作线程池执行阻塞逻辑
          .emitOn(executor -> vertx.getDelegate().createSharedWorkerExecutor("legacy-service-pool"));
  }
  

• 异常处理直接复用Mutiny能力：CompletionStage执行过程中抛出的所有异常，会被桥接逻辑自动传递到Uni的失败处理链路，不需要额外手动捕获CompletionStage的异常，直接用Mutiny内置的onFailure()系列方法即可完成兜底、重试、统一错误返回等逻辑。
• 生命周期自动匹配：桥接逻辑会自动同步请求的完整生命周期，当REST客户端提前断开连接、取消请求时，会自动触发对应CompletionStage的取消通知，避免后台任务空跑造成的资源浪费，不需要手动编写取消逻辑。

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