一、为什么需要 WebFlux

在传统 Spring MVC 中，一次 HTTP 请求往往对应一个线程：线程在读取请求、执行业务、访问数据库或调用下游 HTTP 时被阻塞，线程池耗尽就会表现为延迟飙升、拒绝服务。随着 I/O 密集 场景（网关、BFF、聚合接口、高并发读多写少 API）增多，非阻塞 I/O 成为可选的架构手段之一。

Spring WebFlux 建立在 Reactive Streams 与 Project Reactor 之上，默认采用 事件循环 + 少量工作线程 模型，适合高并发、以 I/O 为主的链路。需要强调的是：WebFlux 不是 MVC 的简单替代品，也不是“一定更快”；它的价值在于 资源利用方式 与 背压（Backpressure） 语义，是否采用应结合团队栈、中间件生态与可观测性成本综合评估。

---

二、WebFlux 与 Spring MVC 的本质差异

维度	Spring MVC	Spring WebFlux
编程模型	命令式、同步为主	声明式、异步非阻塞为主
线程模型	每请求一线程（典型）	Netty 事件循环 + 弹性调度
返回值	String、Object、ResponseEntity 等	Mono<T>、Flux<T> 等
阻塞调用	常见且自然	会占用事件循环，需避免或隔离
生态	Servlet、大量同步库	Reactor、WebClient、R2DBC 等

结论：若业务中大量依赖 阻塞式 JDBC、阻塞式 HTTP 客户端、文件同步读写，在未做线程隔离的前提下强行上 WebFlux，往往得不偿失。更合理的做法是：非阻塞栈尽量贯穿，或在边界用 boundedElastic 等调度器包一层并严格控制并发。

---

三、响应式核心：Mono、Flux 与背压

WebFlux 的“血液”是 Reactor。

• Mono<T>：0 或 1 个元素的异步序列，适合单体结果，如一次 DB 查询、一次 HTTP 响应体。
• Flux<T>：0 到 N 个元素的异步序列，适合列表流、SSE、分块传输等。

背压指：下游消费速度可以反向影响上游生产速度，避免“生产过快撑爆内存”。Reactor 在运行时通过 请求（request） 机制落实这一语义。编写业务时，常见操作符包括：

• map、flatMap：转换与异步编排（flatMap 常用于串联异步 I/O）。
• filter、take、timeout：过滤、限量、超时。
• onErrorResume、onErrorReturn：错误恢复策略。
• publishOn、subscribeOn：线程切换（需谨慎，避免在事件循环上阻塞）。

理解 “一切尽量以 Publisher 表达” 是阅读与编写 WebFlux 代码的前提。

---

四、Spring WebFlux 技术栈概览

在 Spring Boot 中引入 WebFlux，通常意味着：

1. 运行时：默认 Netty（也可使用 Servlet 3.1+ 的异步容器，但 Netty 更常见）。
2. 编程模型二选一或混用：
   • 注解式：@RestController + 返回 Mono / Flux（与 MVC 相似，但语义不同）。
   • 函数式路由：RouterFunction + HandlerFunction（路由与处理逻辑显式组合）。
3. 客户端：优先 WebClient（非阻塞），替代阻塞的 RestTemplate。
4. 数据访问：关系型可考虑 R2DBC；Mongo 等也有响应式驱动；若仍用阻塞 JDBC，应评估是否退回到 MVC 或做隔离。

---

五、快速入门：依赖与最小应用

5.1 Maven 依赖（示例）

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-webflux</artifactId>

</dependency>

注意：不要同时引入 spring-boot-starter-web 与 spring-boot-starter-webflux 作为默认 Servlet 栈，除非你很清楚自己在做 WebFlux + MVC 并存 的进阶场景（Spring Boot 官方文档有专门说明），否则新手项目应保持单一 Web 栈。

5.2 一个最小的非阻塞 Controller

@RestController

@RequestMapping("/api/users")

public class UserController {

@GetMapping("/{id}")

public Mono<User> getById(@PathVariable String id) {

return Mono.just(new User(id, "demo"));

}

@GetMapping

public Flux<User> list() {

return Flux.range(1, 3)

.map(i -> new User(String.valueOf(i), "u" + i));

}

}

此处 Mono.just 仅为演示；真实项目中 Mono 往往来自 DB / RPC / WebClient。

---

六、注解式 WebFlux：编写要点

6.1 返回值类型

• 返回 Mono<ServerResponse> 并不等同于 MVC 里的 ResponseEntity 写法习惯；注解控制器里更常见的是 Mono<User>、Mono<ResponseEntity<User>> 等。
• void 或同步返回 POJO 可以 工作，但会削弱响应式栈的意义，且容易隐藏阻塞。

6.2 请求体读取

使用 @RequestBody 接收 JSON 时，类型可以是 Mono<CreateUserRequest>，表示反序列化与订阅链结合：

@PostMapping

public Mono<User> create(@RequestBody Mono<CreateUserRequest> body) {

return body.flatMap(req -> {

// 调用 UserService 返回 Mono<User>

return Mono.just(new User(req.name(), "new-id"));

});

}

6.3 过滤器与 WebFilter

在 WebFlux 中常用 WebFilter 实现鉴权、链路 ID、日志等横切逻辑，语义接近 Servlet Filter，但运行在响应式管道上。注意 不要在 Filter 里阻塞，需要阻塞时应切换到专用调度器并限制并发。

---

七、函数式路由：RouterFunction 与实践场景

函数式模型将 路由 与 处理器 分离，适合：

• 中大型服务中 按模块拆分路由表；
• 需要 可测试的路由组合（纯 Java DSL）；
• 与 Spring Cloud Gateway 风格相近的团队偏好。

示例：

@Configuration

public class UserRoutes {

@Bean

public RouterFunction<ServerResponse> userRouter(UserHandler handler) {

return RouterFunctions.route()

.GET("/fn/users/{id}", handler::getById)

.GET("/fn/users", handler::list)

.build();

}

}

UserHandler 的方法通常返回 Mono<ServerResponse>，对状态码、Header、Body 有更细粒度控制。

---

八、WebClient：非阻塞 HTTP 客户端最佳实践

WebClient 是 WebFlux 生态中使用频率最高的组件之一。

8.1 创建与复用

应 注册为 Bean 并复用（连接池、线程资源与配置复用），避免每次请求 new：

@Bean

public WebClient downstreamWebClient(WebClient.Builder builder) {

return builder

.baseUrl("https://api.example.com")

.defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE)

.build();

}

8.2 超时与重试

生产环境必须配置 连接超时、读写超时，并结合 熔断/舱壁（如 Resilience4j）使用。Reactor 提供 timeout 操作符；重试需避免对 非幂等写操作 盲目重试。

8.3 错误体解析

下游返回 4xx/5xx 时，应显式读取 ClientResponse 的 body 并映射为业务异常，而不是在链路末端才得到模糊错误。

---

九、数据访问：R2DBC 与“阻塞隔离”

9.1 R2DBC 简介

R2DBC（Reactive Relational Database Connectivity）提供面向关系型数据库的响应式 API。Spring Data R2DBC 可简化 Repository 定义，返回 Mono / Flux。

典型注意点：

• 连接池选型与参数调优（最大连接数、获取超时）；
• 事务在响应式模型下需使用 TransactionalOperator 或 @Transactional 在响应式代理上`（版本与配置需对照官方文档）；
• SQL 与索引设计不当在非阻塞下同样会拖垮 SLA。

9.2 若必须使用阻塞 JDBC

可以：

• 退回 Spring MVC；
• 或使用 publishOn(Schedulers.boundedElastic()) 将阻塞调用限制在 有界线程池，并设置 超时与并发上限，避免占满事件循环。

---

十、全局异常与问题定位

10.1 @ControllerAdvice 的响应式变体

仍可使用 @ControllerAdvice 配合 @ExceptionHandler，返回 Mono<ProblemDetail> 或 Mono<ResponseEntity<...>>，以统一错误模型（RFC 7807 Problem Details 在 Spring 6 中更易用）。

10.2 可观测性

建议接入：

• Micrometer + Prometheus：关注事件循环延迟、线程池队列、R2DBC 连接池指标；
• 分布式追踪（Micrometer Tracing / OpenTelemetry）：注意 WebFlux 与 WebClient 的 context 传播；
• 日志：为每次请求注入 traceId，在 doOnEach 等钩子中写入 Reactor Context。

---

十一、安全：Spring Security 与 WebFlux

Spring Security 对 WebFlux 提供 SecurityWebFilterChain 配置方式，与 Servlet 的 SecurityFilterChain 不同。典型配置包括：

• authorizeExchange：路径级鉴权；
• jwt / oauth2ResourceServer：资源服务器模式；
• CORS、CSRF（若使用 Session 认证需特别谨慎）。

安全过滤器链同样必须 非阻塞化。

---

十二、测试：WebTestClient

WebTestClient 是测试 WebFlux 的首选：可绑定真实或模拟的 ApplicationContext，支持断言状态码、Header、JSON Body，并可测试 流式接口。

对 WebClient 的单元测试可配合 MockWebServer（OkHttp）模拟下游，避免联调环境依赖。

---

十三、性能与常见误区（生产向）

1. 误区：WebFlux 一定更高吞吐
   CPU 密集计算占主导时，线程模型优势有限，甚至可能更差。

2. 误区：把阻塞调用直接包进 Mono.fromCallable 就算响应式
   若不切换调度器，仍可能在事件循环上阻塞。

3. 误区：滥用 subscribe()
   在 @Controller 中应通过返回 Mono/Flux 由框架订阅；业务代码里随意 subscribe 易导致 背压失效、异常难以处理。

4. 线程与 ThreadLocal
   响应式链路中 ThreadLocal 并不可靠，应使用 Reactor Context 传递请求级数据。

5. 背压与缓冲
   onBackpressureBuffer 等要谨慎设置上限，否则仍有 OOM 风险。

---

十四、何时选 WebFlux，何时坚持 MVC

更适合 WebFlux 的信号：

• 高并发、主要耗时在 网络 I/O、DB I/O；
• 团队愿意统一 非阻塞客户端与数据层；
• 网关、代理、聚合读服务。

更适合 MVC 的信号：

• 大量同步遗留库、复杂事务与 ORM 阻塞栈；
• 团队对 Reactor 调试经验不足且短期无法补齐；
• 以 CPU 计算为主的接口。

---

十五、总结

Spring Boot WebFlux 将 非阻塞 I/O 与 声明式异步编排 引入 Spring 生态，核心载体是 Reactor（Mono/Flux）、Netty、WebClient 以及可选的 R2DBC。落地成功的关键不在于“是否使用了 WebFlux 依赖”，而在于：阻塞是否被隔离或消除、超时与重试是否可控、错误与可观测性是否完整。建议在试点服务中从 读多写少 API + WebClient 下游 切入，建立指标与压测基线，再逐步扩展数据层与模块边界，避免一次性全栈切换带来的维护风险。