概述
在掌握了 Spring MVC 的请求处理全链路和 REST 客户端之后
Spring WebFlux 并非 Spring MVC 的简单替代，而是对 Web 编程模型的重新思考。当 Tomcat 线程池被占满时请求只能排队等待；而在 WebFlux 的事件循环中。线程数量是固定的，请求的处理变成了廉价的异步事件触发。这种模型的转变带来了巨大的吞吐量潜力，但也引入了背压协调、错误信号传播和线程调度等新的复杂性。
主要要点
事件循环模型： WebFlux 基于 Netty 的 I/O 工作线程，不再为每个请求分配独立线程。痛点：旧程序因“每请求一线程”导致 CPU 利用率低、并发受限。
Reactor 线程调度： Schedulers 的分类及其在 WebFlux 中的默认使用规则。痛点：误把阻塞调用放在 I/O 线程上，引发服务卡顿。
背压传播： 下游消费速度如何向上游传递，还有如何利用 limitRate 等操作符进行流量整形。痛点：大量数据一次性冲垮内存，出现 OOM。
响应式错误处理： onErrorResumeonErrorReturn 与全局错误 WebExceptionHandler。痛点：错误未被捕获导致请求直接掉线。
阻塞边界检测： BlockHound 在开发期间的作用，还有调用阻塞 API 对事件循环的致命影响。痛点：上线后才发现隐藏阻塞，服务雪崩。
响应式流与 Reactor 主要回顾
从响应式流规范来看，Publisher、Subscriber、Subscription、Processor
响应式流是一个面向非阻塞背压的异步流处理标准。不过，它由四个主要接口定义，分布在 Java 的 java.util.concurrent.Flow 中，但 Spring WebFlux 和 Reactor 基于 org.reactivestreams.
Publishersubscribe.
SubscriberonSubscribe,onNext,onError,onComplete.
Subscriptionrequest/cancel.
Processor
Reactor 的 Mono 与 Flux
Mono
Flux: 代表 N 个元素的异步序列，例如事件流或集合迭代。
再看从创建到订阅，完整生命周期示例
{
if {
throw new RuntimeException;}
return i * 2;})
.log，// 打印所有信号
// 订阅
dataStream.subscribe(
v -> System.out.println。e -> System.err.println,-> System.out.println
);-->
Pain point: 如果忘记在业务代码里捕获异常。会导致整个链路直接进入 onError,从而中断后续数据发送。
WebFlux 线程模型：从 Servlet 线程池到事件循环
传统 Servlet 容器的“每请求一线程”模型
sequenceDiagram
actor Client as 客户端
participant Connector as HTTP连接器
participant ThreadPool as 线程池
participant Servlet as 业务Servlet
Client->+Connector: 发起请求
Connector->+ThreadPool: 分配 Thread-
ThreadPool->+Servlet: Thread- 执行service
Note over Thread-,Servlet: 阻塞等待DB/IO...
Servlet-->-ThreadPool: 返回响应
ThreadPool-->-Connector: 释放Thread-
Connector-->-Client: 响应
Note over ThreadPool: 当200个线程全被阻塞时新请求只能排队等待。
Pain point: 并发量 ≈ 线程池大小。一旦 CPU/内存不足，需要频繁扩容导致资源浪费。
WebFlux 的 Event Loop 模型
sequenceDiagram
actor Client1 as 客户端1
actor Client2 as 客户端2
participant NIOServer as NIO服务器
participant Pipeline1 as ChannelPipeline1
participant Pipeline2 as ChannelPipeline2
participant Application as 应用层
Client1->NIOServer: 建立连接→Channel1
Client2->NIOServer: 建立连接→Channel2
NIOServer->Application: Trigger Channel1 read event
Application-->Pipeline1: 非阻塞读取 & 业务处理
Application->NIOServer: 返回。循环...
NIOServer->Application: Trigger Channel2 read event
Application-->Pipeline2: 非阻塞读取 & 业务处理
Application->NIOServer: 返回...
Note over Application: 线程始终忙碌但不阻塞，实现高并发。
Pain point: 如果在 Event Loop 中误用了阻塞 API，会导致所有连接瞬间失效。
Pain point: 开发者往往忽视“同一个请求可能跨多个 Event Loop”，导致 ThreadLocal 丢失信息。
Spring WebFlux 的异步运行时：Reactor Netty 与 HttpServer适配
public class HttpServer {
public static HttpServer create { ... }
public HttpServer handle(BiFunction handler) { ... }
public final DisposableServer bindNow { ... } // 内部调用 TcpServer.bindNow
}
The adapter bridges Netty’s request/response to Spring’s reactive abstractions:
public class ReactorHttpHandlerAdapter implements BiFunction {
private final HttpHandler httpHandler;@Override
public Publisher apply(HttpServerRequest reactorRequest,HttpServerResponse reactorResponse) {
NettyDataBufferFactory bufferFactory = new NettyDataBufferFactory);ServerHttpRequest adaptedRequest = new ReactorServerHttpRequest;ServerHttpResponse adaptedResponse = new ReactorServerHttpResponse;return this.httpHandler.handle;}
}
至于线程调度器，Schedulers 的分工
Schedulers.immediate : 当前线程同步执行。
Schedulers.single : 单一可复用线程，用于需要顺序执行且不涉及 I/O 的任务。
Schedulers.parallel : 固定大小工作池，适合 CPU 密集型计算。
Schedulers.boundedElastic : 有界弹性池。用于封装不可避免的阻塞调用，如 JD娱乐、文件 IO。
Pain point: If you wrap whole controller in boundedElastic you lose benefits of event‑loop model.
// 正确做法：仅封装真正阻塞的方法
Mono blockingWrapper = Mono.fromCallable ->
jdbcTemplate.queryForObject)
.subscribeOn)
.map(user -> {
System.out.println.getName);return user，});
至于背压，响应式管道的流量控制
背压主要机制——Subscription.request
sequenceDiagram
participant Publisher
participant Subscriber
Publisher->Subscriber: onSubscribe
Note over Subscriber: 我只想要3个元素
Subscriber->Publisher: subscription.request
Publisher->Subscriber: onNext
Publisher->Subscriber: onNext
Publisher->Subscriber: onNext
Note over Publisher: 暂停生产。等待下一次 request
Subscriber->Publisher: subscription.request
Publisher->>r">Subscriber": onNext
Publisher->r">Subscriber": onNext
Pain point: If an upstream source ignores request signals,memory can explode.
Reactor 中常见操作符对背压的影响
操作符 背压行为
`map`,`filter`,`doOnNext`
透明传递，下游 request → 上游 request
`flatMap`
内部维护缓冲区，将外层 request 分批转化为多内部 publisher 请求；若内部 publisher 较慢，可出现短暂“背压失真”。
`limitRate`
将一次大的 request 拆分为若干批次以保护下游不被一次性冲垮。
`onBackpressureBuffer`,`onBackpressureDrop`。`onBackpressureLatest`
为不支持背压的源提供自定义缓冲或丢弃策略。}
**举例——缺失背压导致 OOM**
java
Flux.create(emitter -> {
// 忽略 downstream demand
new Thread -> {
long i=0;while{ emitter.next;}
}).start，}).subscribe;// 会抛出 MissingBackpressureException
从**方法**来看。java
source.onBackpressureBuffer(1000,dropped -> log.warn)
.subscribe;
WebFlux 中背压实际落地
`；过滤器或 Controller 对该 Flux 发起 `request` 控制网络读取速率，从而防止一次性把整个体加载进内存。
` 时Netty 在 socket 缓冲区有空余才会向上游
`request` 数据，实现自然回流。
. 错误处理：从信号到 HTTP 错误响应
Reactor 错误信号与恢复操作符
一旦任何阶段抛出异常，它会被包装成 < code > onError
信号沿着管道向下传播直到被捕获。mermaid
flowchart LR
subgraph 管道
A --> B --> C
end
B -- onError --> D{onErrorResume?}
D -- 捕获并返回备选流 --> E
D -- 未捕获 --> F
E --> G
Pain point : 未使用 error operator 捕获异常 → 流直接终止 → 客户端收到空响应或连接关闭。}
**主要恢复操作符**
java
// 静态降级值
mono.onErrorReturn;// 动态降级
flux.onErrorResume(ex -> {
if return fallbackService;return Mono.error;// 向上传递
})，// 包装异常
flux.onErrorMap);// 重试
mono.retryWhen)
.maxBackoff)
.jitter);### 全局错误处理
* **注解模式** ：使用 `@RestControllerAdvice` + `@ExceptionHandler` 返回 `Mono` 保持响应式链。* **函数式模式** ：实现 `WebExceptionHandler` 接口；Spring 默认提供 `DefaultErrorWebExceptionHandler` 将异常映射为 JSON/HTML。java
@Component @Order // 高优先级覆盖默认实现
public class CustomErrorWebExceptionHandler extends AbstractErrorWebExceptionHandler {
public CustomErrorWebExceptionHandler(ErrorAttributes attrs。ApplicationContext ctx,ServerCodecConfigurer codecCfg){
super,ctx);super.setMessageWriters);super.setMessageReaders);}
@Override protected RouterFunction
getRoutingFunction{
return RouterFunctions.route,this::renderErrorResponse);}
private Monoa renderErrorResponse{
MapM=getErrorAttributes(req,ErrorAttributeOptions.defaults);return ServerResponse.statusM.get)
.contentType
.bodyValue;}
}
Pains : 若忘记返回 `< Mono >` 而写成普通对象。则错误不会走响应式方法，会直接返回空白页面或500页面。
. 请求处理组件与过滤器
##;###，##
...
。
