Quarkus/SmallRye Messaging消费者阻塞Vertx线程时为何返回nack

云上老周

2026-8-30

问题根因

一开始把Vert.x线程阻塞提示当成普通警告是错误认知。SmallRye Reactive Messaging默认会将@Incoming标记的消息处理方法直接调度到Vert.x Event Loop（事件循环）线程执行，这类线程严禁运行任何阻塞操作，框架一旦检测到线程阻塞等待行为，会直接抛出IllegalStateException终止执行，不是仅输出警告就放行。

消息自动返回nack（否定确认）的逻辑也很直接：消息处理方法抛出未捕获异常时，SmallRye Messaging会自动判定本次消息处理失败，向消息中间件返回nack，触发后续重投、死信队列等逻辑。

从异常栈可以定位到具体触发点：
process方法调用的someService.update链路中，叠加了Quarkus Cache拦截器、Fault Tolerance重试拦截器，这些组件的同步实现底层依赖Mutiny的UniBlockingAwait.await做阻塞等待，直接触发了Event Loop线程的阻塞校验，抛异常中断了整个处理流程。

@Blocking注解生效原理

给process方法加上@Blocking后问题消失，本质是这个注解会显式告知框架：当前方法是阻塞逻辑，不要调度到Event Loop线程执行，要转发到专门的阻塞工作线程池运行。阻塞工作线程池本身就是为阻塞IO、长耗时任务设计的，允许线程阻塞等待，自然不会触发线程类型校验报错，方法能正常执行完成后，消息就会被正常ack，不会再返回nack。

问题复现代码与核心异常

原消息处理器实现：

@Incoming("topic-in")
public void process(String event) {
    // 底层会发起HTTP REST客户端请求
    someService.update(event);
}

核心报错信息：

java.lang.IllegalStateException: The current thread cannot be blocked: vert.x-eventloop-thread-0
调用链路：Event Loop线程调度process方法 → 执行带@CacheResult、@Retry注解的服务逻辑 → 拦截器内触发阻塞等待 → 线程阻塞校验抛出异常

额外注意事项

阻塞操作不局限于显式的Thread.sleep()、JDBC调用：Quarkus生态中很多注解的同步实现（比如@CacheResult、同步REST客户端调用、@Retry同步流程）底层都会做阻塞等待，在Event Loop线程上调用同样会触发报错
除了加@Blocking切到阻塞线程池，也可以将方法改为响应式签名（返回Uni<Void>/Multi<Void>），全程使用非阻塞响应式API链式调用，不包含任何阻塞等待逻辑，也可以直接在Event Loop线程上正常运行
不要无差别给所有@Incoming方法加@Blocking：阻塞工作线程池的线程数有上限，大量阻塞任务堆积会拉低整体消费吞吐量，纯非阻塞逻辑直接跑在Event Loop上性能更高

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