WEBKT

Spring Cloud Gateway 适配 Java 21 虚拟线程：高性能网关的避坑与实战指南

2 0 0 0

随着 Java 21 的正式发布，虚拟线程（Virtual Threads，即 Project Loom）成为了 Java 生态中最受瞩目的特性之一。很多开发者跃跃欲试，希望将这一特性应用到微服务架构的“咽喉”—— Spring Cloud Gateway 中，以期获得吞吐量的飞跃。

然而，在反应式编程（Reactive Programming）主导的 Spring Cloud Gateway 中，直接开启虚拟线程真的能带来性能提升吗？这里面有哪些不为人知的深坑？本文将深度剖析 Spring Cloud Gateway 适配 Java 21 虚拟线程的底层逻辑、实战配置以及避坑指南。

一、 核心误区：开启 spring.threads.virtual.enabled=true 就够了吗？

在 Spring Boot 3.2+ 中，我们只需要在 application.yml 中配置：

spring:
  threads:
    virtual:
      enabled: true

这行配置会让 Tomcat、Jetty 等 Servlet 容器使用虚拟线程来处理 HTTP 请求。但是，Spring Cloud Gateway 是基于 WebFlux 和 Netty 构建的，默认并不是 Servlet 容器。

Netty 本质上是一个基于事件循环（EventLoop）的非阻塞 I/O 引擎。这意味着，即使你开启了上述配置，Netty 的 EventLoop 线程仍然是传统的平台线程（Platform Threads），网关的 I/O 处理逻辑并不会自动跑在虚拟线程上。

那么，虚拟线程对网关还有意义吗？

答案是：有，但场景不同。

Netty 的非阻塞模型在处理纯路由、转发等 I/O 密集型任务时已经极度高效，并不需要虚拟线程的介入。虚拟线程在 Spring Cloud Gateway 中的真正用武之地，是解决自定义过滤器（GlobalFilter / GatewayFilter）中的阻塞操作。

在实际业务中，我们经常需要在网关过滤器中做一些“不得不阻塞”的事情，例如：

  • 调用传统的同步安全认证接口（如旧版的 OAuth2 / LDAP 服务）
  • 使用阻塞式的数据库驱动（如 JDBC）读取灰度发布配置
  • 进行复杂的解密、验签等 CPU 密集型或涉及同步 I/O 的操作

在过去，这些阻塞操作会直接卡死 Netty 的 EventLoop 线程，导致网关整体吞吐量雪崩。引入虚拟线程，就是为了优雅地承接这部分阻塞任务。

二、 实战：在 Spring Cloud Gateway 中正确使用虚拟线程

要在网关中真正发挥虚拟线程的作用，我们需要将那些“不得不阻塞”的过滤器逻辑，分发到虚拟线程调度器上执行。

1. 环境准备

确保你的项目依赖版本符合以下要求：

  • JDK: 21
  • Spring Boot: 3.2.x 及以上
  • Spring Cloud: 2023.0.x (对应 Spring Cloud Gateway 4.1.x) 及以上

2. 构建自定义的虚拟线程调度器（Scheduler）

在 Reactor 中，我们习惯使用 Schedulers.boundedElastic() 来处理阻塞任务。现在，我们可以利用 Java 21 的虚拟线程，自定义一个性能更强、几乎无上限的虚拟线程调度器：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import reactor.core.scheduler.Scheduler;
import reactor.core.scheduler.Schedulers;

import java.util.concurrent.Executors;

@Configuration
public class VirtualThreadSchedulerConfig {

    @Bean(name = "virtualThreadScheduler")
    public Scheduler virtualThreadScheduler() {
        // 使用 Java 21 的虚拟线程线程池构建 Reactor 调度器
        return Schedulers.fromExecutorService(
                Executors.newVirtualThreadPerTaskExecutor(),
                "gateway-virtual-thread"
        );
    }
}

3. 在自定义过滤器中调度阻塞任务

有了这个调度器，我们就可以在网关过滤器中，将阻塞逻辑“委派”给虚拟线程执行，从而解放 Netty 的 EventLoop 线程。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Scheduler;

@Component
public class VirtualThreadAuthFilter implements GlobalFilter, Ordered {

    @Autowired
    @Qualifier("virtualThreadScheduler")
    private Scheduler virtualThreadScheduler;

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        return Mono.fromCallable(() -> {
            // 这里模拟一个不得不进行的同步阻塞操作，比如调用外部 RPC、JDBC 查询等
            return executeBlockingAuthCall(exchange);
        })
        // 关键点：将上述阻塞操作发布到虚拟线程调度器上执行
        .subscribeOn(virtualThreadScheduler)
        .flatMap(authResult -> {
            if (authResult) {
                return chain.filter(exchange);
            } else {
                exchange.getResponse().setRawStatusCode(401);
                return exchange.getResponse().setComplete();
            }
        });
    }

    private boolean executeBlockingAuthCall(ServerWebExchange exchange) {
        try {
            // 模拟阻塞 50ms
            Thread.sleep(50);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        return true;
    }

    @Override
    public int getOrder() {
        return -100; // 保证在高优先级执行
    }
}

三、 深度避坑指南

将虚拟线程引入 Spring Cloud Gateway 并非百利而无一害。由于底层的 Netty 依然运行在平台线程上，且很多 Java 类库尚未完全适配 Java 21，实践中必须注意以下致命陷阱：

1. 锁钉（Thread Pinning）问题

虚拟线程是由 JVM 调度在平台线程（Carrier Thread）之上的。如果虚拟线程在执行过程中遇到了：

  • synchronized 块或 synchronized 方法
  • 调用了本地方法（Native Method）或 Foreign Function (Project Panama)

此时，虚拟线程会“钉死”（Pin）在平台线程上，导致 JVM 无法将其切换走。如果发生大面积 Pinning，虚拟线程将退化为普通的同步阻塞模型，甚至导致线程饥饿。

解决方案：

  • 检查你的网关过滤器中引入的第三方 SDK（如 Redis 客户端、数据库驱动、安全验签工具）。
  • 尽量使用基于 ReentrantLock 的类库，替换掉带有 synchronized 关键字的旧库。
  • 启动 JVM 时添加参数 -Djdk.tracePinnedThreads=full，在测试环境监控是否存在虚拟线程锁钉现象。

2. 不要对纯非阻塞/响应式代码使用虚拟线程

如果你的网关逻辑已经是彻底的响应式代码（如使用 WebClient 进行异步调用，使用 Reactive Redis），绝对不要将其切换到虚拟线程。

非阻塞 I/O 本身就是高效的，强行将其放入虚拟线程执行，不仅不会提升性能，反而会因为虚拟线程的创建、销毁和上下文切换（虽然很轻量，但也有开销）导致网关吞吐量下降。

3. ThreadLocal 内存泄露与滥用

很多旧项目喜欢在 Gateway Filter 中使用 ThreadLocal 传递用户信息或 TraceID。
在虚拟线程的世界里，由于虚拟线程的创建极其廉价，数量可能瞬间达到数十万。如果这些虚拟线程中存入了较大的 ThreadLocal 变量且未及时清理，会导致内存迅速撑爆。

解决方案：

  • 在 WebFlux/Gateway 中，优先使用 WebFlux 自带的 ReactiveAdapterRegistry 或 Reactor 的 Context 来传递上下文。
  • 如果必须使用，考虑 Java 21 引入的 ScopedValue（虽然目前仍是预览特性），或者确保在 try-finally 中绝对调用了 ThreadLocal.remove()。

四、 总结

在 Spring Cloud Gateway 中适配 Java 21 虚拟线程，是一场**“局部战争”**。

  1. 不要期望一键开启配置就能提升整体性能。对于纯响应式的网关路由，Netty 原生的 EventLoop 依然是最佳选择。
  2. 虚拟线程的真正价值在于“解耦阻塞”。它是一剂特效药，用来解决自定义过滤器中不可避免的同步 I/O、传统 SDK 调用和复杂计算。
  3. 通过自建 virtualThreadScheduler，配合 subscribeOn，我们可以优雅地在网关中混用响应式流与同步阻塞逻辑，同时规避了传统的线程池耗尽风险。
架构视界 Java 21虚拟线程

评论点评