Spring Boot + WebFlux 全面使用指南-平芜编程栈

一、什么是 Spring WebFlux？

定位：Spring Framework 5+ 提供的响应式 Web 框架，与 Spring MVC 并列；
核心目标：支持非阻塞、异步、事件驱动的高并发 Web 应用；
底层依赖：
- 响应式流规范（Reactive Streams）
- Project Reactor（Mono/Flux）
- 非阻塞服务器（默认 Netty，也支持 Undertow、Servlet 3.1+ 容器）

✅ WebFlux ≠ WebMVC 替代品，而是互补技术栈，适用于不同场景。

二、何时使用 WebFlux？

场景	推荐
高并发 I/O 密集型（API 网关、实时推送、IoT）	✅ 强烈推荐
全链路响应式技术栈（R2DBC + WebClient + Reactive MQ）	✅
低并发传统业务系统（后台管理、简单 CRUD）	❌ 用 WebMVC 更简单
强事务性/复杂 SQL（需 Hibernate/JPA）	❌ 不适合

三、快速入门：创建 WebFlux 项目

1. 使用 Spring Initializr（https://start.spring.io/）

选择：

Project: Maven / Gradle
Language: Java
Spring Boot: 3.x（推荐）
Dependencies:
- Spring Reactive Web
- Spring Data R2DBC（如需数据库）
- H2 Database或MariaDB Driver（根据需要）

2. 手动添加依赖（Maven）

<dependencies><!-- WebFlux 核心 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-webflux</artifactId></dependency><!-- 响应式数据库（以 MariaDB 为例） --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-r2dbc</artifactId></dependency><dependency><groupId>org.mariadb</groupId><artifactId>r2dbc-mariadb</artifactId><version>1.1.5</version></dependency><dependency><groupId>org.mariadb</groupId><artifactId>mariadb-java-client</artifactId><scope>runtime</scope></dependency><!-- 测试 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><dependency><groupId>io.projectreactor</groupId><artifactId>reactor-test</artifactId><scope>test</scope></dependency></dependencies>

3. 启动类（无需特殊注解）

@SpringBootApplicationpublicclassWebfluxDemoApplication{publicstaticvoidmain(String[]args){SpringApplication.run(WebfluxDemoApplication.class,args);}}

🔍 启动日志将显示：Netty started on port 8080

四、两种编程模型

A. 注解式（Annotation-based）— 类似 Spring MVC

@RestController@RequestMapping("/users")publicclassUserController{@AutowiredprivateUserRepositoryuserRepository;// 返回单个对象@GetMapping("/{id}")publicMono<User>getUser(@PathVariableStringid){returnuserRepository.findById(id);}// 返回列表流@GetMappingpublicFlux<User>getAllUsers(){returnuserRepository.findAll();}// 创建用户@PostMappingpublicMono<User>createUser(@RequestBodyUseruser){returnuserRepository.save(user);}// SSE：服务器推送事件@GetMapping(value="/stream",produces=MediaType.TEXT_EVENT_STREAM_VALUE)publicFlux<String>streamEvents(){returnFlux.interval(Duration.ofSeconds(1)).map(seq->"Event #"+seq);}}

✅ 优点：学习成本低，与 MVC 风格一致
⚠️ 注意：方法必须返回Mono或Flux

B. 函数式（Functional）— 纯函数式路由

1. 定义 Handler

@ComponentpublicclassUserHandler{privatefinalUserRepositoryuserRepository;publicUserHandler(UserRepositoryuserRepository){this.userRepository=userRepository;}publicMono<ServerResponse>getUser(ServerRequestrequest){Stringid=request.pathVariable("id");Mono<User>user=userRepository.findById(id);returnuser.flatMap(u->ServerResponse.ok().bodyValue(u)).switchIfEmpty(ServerResponse.notFound().build());}publicMono<ServerResponse>getAllUsers(ServerRequestrequest){Flux<User>users=userRepository.findAll();returnServerResponse.ok().body(users,User.class);}}

2. 定义 RouterFunction（替代 @RequestMapping）

@ConfigurationpublicclassUserRouter{@BeanpublicRouterFunction<ServerResponse>userRoutes(UserHandlerhandler){returnroute().GET("/users/{id}",handler::getUser).GET("/users",handler::getAllUsers).build();}}

✅ 优点：更符合响应式思想，易于单元测试，无反射开销
💡 适合构建轻量级、高内聚的 API

五、响应式数据访问（R2DBC）

1. 实体类

@Table("users")publicclassUser{@IdprivateLongid;privateStringname;privateStringemail;// constructors, getters, setters}

2. Repository

publicinterfaceUserRepositoryextendsReactiveCrudRepository<User,Long>{Flux<User>findByEmail(Stringemail);}

3. application.yml 配置

spring:r2dbc:url:r2dbc:mariadb://localhost:3306/mydbusername:rootpassword:password

支持连接池（需引入io.r2dbc:r2dbc-pool）

六、响应式 HTTP 客户端：WebClient

替代RestTemplate，非阻塞调用外部服务：

@ServicepublicclassExternalServiceClient{privatefinalWebClientwebClient;publicExternalServiceClient(){this.webClient=WebClient.builder().baseUrl("https://api.example.com").build();}publicMono<UserProfile>fetchProfile(StringuserId){returnwebClient.get().uri("/profiles/{id}",userId).retrieve().bodyToMono(UserProfile.class).onErrorResume(e->Mono.empty());// 错误降级}}

七、全局异常处理

@ControllerAdvicepublicclassGlobalExceptionHandler{@ExceptionHandler(UserNotFoundException.class)publicMono<ResponseEntity<String>>handleUserNotFound(Exceptionex){returnMono.just(ResponseEntity.status(HttpStatus.NOT_FOUND).body("User not found"));}@ExceptionHandler(Exception.class)publicMono<ResponseEntity<String>>handleGeneral(Exceptionex){returnMono.just(ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Internal error"));}}

也可使用函数式方式注册WebExceptionHandler。

八、测试：WebTestClient

@SpringBootTest(webEnvironment=SpringBootTest.WebEnvironment.RANDOM_PORT)classUserControllerTest{@AutowiredprivateWebTestClientwebClient;@TestvoidshouldGetUser(){webClient.get().uri("/users/1").exchange().expectStatus().isOk().expectBody(User.class).value(user->assertThat(user.getName()).isEqualTo("Alice"));}}

九、性能与配置优化

1. 调整 Netty 参数（application.yml）

server:netty:connection-timeout:30smax-in-memory-size:10MB# 防止 OOM

2. 启用背压控制

Flux.range(1,1000).limitRate(100)// 控制上游发射速率.onBackpressureBuffer(500);// 缓冲溢出数据

3. 监控与指标

集成 Micrometer + Prometheus，监控reactor.netty.connection.provider.active.connections等指标。

十、常见陷阱与最佳实践

问题	建议
在 WebFlux 中调用 JDBC / Thread.sleep()	❌ 会阻塞 EventLoop，导致服务不可用
混合使用 WebMVC 和 WebFlux	⚠️ 可以共存，但不要在同一个 Controller 中混用
忽略背压	⚠️ 大流量下可能 OOM，务必使用`limitRate`/`onBackpressureXXX`
过度使用`block()`	❌ 破坏响应式模型，仅用于测试或边界转换