Spring MVC 中的 WebClient:.block() 与返回 Mono 的线程行为
本文目录
在 Spring MVC 中,WebClient 也能使用非阻塞 HTTP 通信;但控制器调用 .block() 会使 MVC 请求线程等待结果。 返回 Mono 可让 MVC 将其适配到 Servlet 异步处理并释放初始请求线程。客户端通信与服务器请求处理是不同的问题。
本文讨论 Tomcat 上的 Spring MVC 与使用 Reactor Netty 的 WebClient。其他 HTTP 连接器可能使用不同线程名称与资源。示例使用 Spring Boot 3.5.16、JDK 21 和 Gradle 8.14.3 复现;这不意味着验证了当前所有 Boot 版本。
添加 WebClient 会让服务器使用 WebFlux 吗?
服务端 MVC 和用于外部调用的 WebClient 职责不同。这里 Tomcat 与 DispatcherServlet 处理传入请求,WebClient 的 Reactor Netty 连接器处理出站 HTTP。
在 Boot 3.5 中,同时添加 spring-boot-starter-web 与 spring-boot-starter-webflux 时默认选择 MVC。这支持为了使用 WebClient 而添加 WebFlux starter 的应用。如果显式更改应用类型或使用其他服务器配置,需要另行确认。Boot 的 MVC 与 WebFlux 选择
.block() 和返回 Mono 从哪里分开?
绿色表示 Servlet 和 MVC 的职责,蓝色表示 Reactor Netty。异步路径中的两个分支可能重叠;外部响应不一定在初始请求线程返回之后才到达。图主要表示成功信号,代码中的错误信号映射为 HTTP 状态后进入 MVC 错误处理。
| 阶段 | .block() 后返回值 |
返回 Mono |
|---|---|---|
| 订阅 | 由 .block() 执行 |
MVC 订阅返回类型 |
| 等待出站 HTTP | 请求线程等待 | Servlet 异步处理可能释放初始请求线程 |
| 接收响应体后 | 客户端回调提供结果并解除等待 | 结果信号交给 MVC 异步处理 |
| 最终 HTTP 响应 | MVC 序列化并写入返回值 | MVC 重新派发后序列化并写入 |
retrieve().bodyToMono(...) 组装请求管道。下方新建的 WebClient 管道必须被订阅才会发起 HTTP 请求。订阅两次可能再次发出请求,因此应注意使用 .block() 读取一次后又返回该管道的代码。
MVC 对单值 Mono 的适配类似 DeferredResult。结果准备好后,MVC 向 Servlet 容器重新派发以完成响应。线程池可能复用同一线程,因此不要假设重新派发线程一定不同于初始线程。响应未关闭时,连接和异步请求资源也会保留。返回 Mono 不会使整个 Servlet 响应写入都变为非阻塞。此例返回单值 JSON;流式传输和 SSE 是不同情况。MVC 异步处理与 reactive 返回类型
用两种方式调用同一个外部 API
将以下文件保存到同一项目。它使用 application 插件而非 Boot Gradle 插件,并将 Java toolchain 固定为 21。本地检查使用 Azul JDK 21.0.1;这一历史补丁版本不作为新生产环境的推荐。
settings.gradle
rootProject.name = 'mvc-webclient-execution'
build.gradle
plugins {
id 'java'
id 'application'
}
repositories { mavenCentral() }
java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }
dependencies {
implementation platform('org.springframework.boot:spring-boot-dependencies:3.5.16')
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-webflux'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
application { mainClass = 'example.DemoApplication' }
test {
useJUnitPlatform()
systemProperty 'demo.virtual', providers.gradleProperty('virtual').getOrElse('false')
}
src/main/resources/application.yml
upstream:
base-url: http://127.0.0.1:9091
timeout: 3s
spring:
mvc:
async:
request-timeout: 5s
WebClient 作为 bean 复用,并显式使用 Reactor Netty 连接器。示例的 HttpClient.create() 使用默认共享事件循环和连接池,不会为每个出站请求创建专属 Netty 线程。callbackThread 是响应体生成后执行 map 的线程,不一定是写入最终 Servlet 响应的线程。这里没有添加 publishOn 等调度器切换。WebClient 连接器和共享资源
src/main/java/example/DemoApplication.java
package example;
import java.time.Duration;
import java.util.concurrent.TimeoutException;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.http.HttpStatus;
import org.springframework.http.client.reactive.ReactorClientHttpConnector;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.WebClientResponseException;
import org.springframework.web.server.ResponseStatusException;
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;
import reactor.netty.http.client.HttpClient;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
@Bean
WebClient upstreamClient(WebClient.Builder builder,
@Value("${upstream.base-url}") String baseUrl) {
return builder.baseUrl(baseUrl)
.clientConnector(new ReactorClientHttpConnector(HttpClient.create()))
.build();
}
public record Observation(String mode, String requestThread, boolean requestVirtual,
String callbackThread, boolean callbackVirtual, boolean callbackNonBlocking,
String value) {}
@RestController
static class DemoController {
private final WebClient client;
private final Duration deadline;
DemoController(WebClient client, @Value("${upstream.timeout}") Duration deadline) {
this.client = client;
this.deadline = deadline;
}
private Mono<Observation> fetch(String mode) {
Thread request = Thread.currentThread();
String name = request.getName();
boolean virtual = request.isVirtual();
return client.get().uri("/value").retrieve().bodyToMono(String.class)
.timeout(deadline)
.map(value -> new Observation(mode, name, virtual,
Thread.currentThread().getName(), Thread.currentThread().isVirtual(),
Schedulers.isInNonBlockingThread(), value))
.onErrorMap(WebClientResponseException.class, error ->
new ResponseStatusException(HttpStatus.BAD_GATEWAY,
"upstream HTTP error", error))
.onErrorMap(TimeoutException.class, error ->
new ResponseStatusException(HttpStatus.GATEWAY_TIMEOUT,
"upstream deadline", error));
}
@GetMapping("/block")
Observation blocking() {
return fetch("block").block();
}
@GetMapping("/async")
Mono<Observation> asynchronous() {
return fetch("async");
}
}
}
/block 是用于比较的路径。能够以异步返回结束的控制器可像 /async 一样返回结果 Mono,交给 MVC 订阅。直接调用 .subscribe() 并先返回响应,会使出站调用的结果和错误脱离原始 HTTP 请求。同步使用 WebClient 和控制器返回值
示例中三秒的 timeout 限制从订阅到收到值的时间,没有分别配置连接池获取、连接或单次响应读取的超时。HTTP 错误映射为 502,管道超时映射为 504。连接失败、空响应体和业务错误需要单独定义契约。retrieve() 默认将 HTTP 4xx 和 5xx 视为错误。retrieve 错误处理
本地运行
使用本地 Python 3 HTTP 服务器代替外部服务。/value 在 0.2 秒后返回 hello。该延迟是观察行为的输入,并非性能测量。
upstream.py
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from time import sleep
class Handler(BaseHTTPRequestHandler):
def do_GET(self):
if self.path != '/value':
self.send_error(404)
return
sleep(0.2)
body = b'hello'
self.send_response(200)
self.send_header('Content-Type', 'text/plain; charset=utf-8')
self.send_header('Content-Length', str(len(body)))
self.end_headers()
self.wfile.write(body)
ThreadingHTTPServer(('127.0.0.1', 9091), Handler).serve_forever()
在第一个终端运行。
python3 upstream.py
在第二个终端选择 JDK 21,并使用 Gradle 8.14.3 运行。
gradle run
在第三个终端调用两个路径:
curl --fail --show-error --silent http://127.0.0.1:8080/block
curl --fail --show-error --silent http://127.0.0.1:8080/async
两个路径都返回含 hello 的 JSON。使用普通请求线程时,我们观察到 requestVirtual=false;此例的 Netty 回调为 callbackVirtual=false 和 callbackNonBlocking=true。线程名称和编号每次可能不同,仅看响应 JSON 中的 mode 无法证明等待时请求线程已释放。
启用虚拟线程后有什么变化?
停止前面的应用,再以虚拟线程设置运行相同代码。
gradle run --args='--spring.threads.virtual.enabled=true'
此设置下两个路径的 requestVirtual 均变为 true。在 .block() 路径中,调用的虚拟线程仍等待结果,但通常可 park 的等待不同于持续占用载体平台线程。需要另行确认 pinning 与所运行 JDK 的差异。JDK 21 虚拟线程调度和 pinning 启用虚拟线程没有使此例的 Reactor Netty 回调变成虚拟线程。 Boot 虚拟线程配置
虚拟线程不会增加外部服务处理能力、HTTP 连接数或 DB 连接数。积压请求的上限需要另行设计,例如数据库信号量和准入控制。
可以在回调中调用 JDBC 吗?
从 MVC 调用 WebClient 不意味着后续 map 也运行在 MVC 请求线程。此例中若在 map 里执行 JDBC 查询或长时间文件读取,可能阻塞 Netty 事件循环。反过来,并非每个 Mono 都运行在专用线程。操作符的执行位置取决于订阅、信号和调度器切换。Reactor 线程和调度器
对于同步操作较多的服务,可比较在 MVC 同步调用流程中限定资源,与保持异步链并把阻塞工作隔离到独立执行器两种方式。简单同步 HTTP 调用也可参考选择 RestClient 或 WebClient。仅切换调度器不能解决 DB 或下游服务过载。
实际验证范围
验证测试在随机端口上的真实 Tomcat 和本地 HTTP 服务器运行。共通过十六项检查:普通请求线程和虚拟线程各八项。
- 同时存在两个 starter 时选择 Servlet 上下文、Tomcat 和 DispatcherServlet
- 组装管道时不发请求;订阅和重新订阅时发出请求
- 外部响应被暂缓时
.block()请求线程等待,以及Mono进入 Servlet 异步处理 - 请求线程是否为虚拟线程,以及响应回调是否非阻塞、是否为虚拟线程
- 两条路径的 HTTP 错误映射为 502、管道超时映射为 504
若自行运行测试,将上述验证代码保存为 src/test/java/example/ExecutionTest.java 后执行。
gradle clean test
gradle test -Pvirtual=true --rerun-tasks
测试使用暂缓响应的 latch 观察状态,不根据短运行时间推断异步。未验证吞吐量比较、真实外部服务、DB 或 TLS、客户端断开或远程副作用取消。尤其是,管道取消不保证远程服务器工作取消或事务回滚。
讨论