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？

三、快速入门：创建 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 开发 Checklist

• 使用spring-boot-starter-webflux
• 返回类型为Mono<T>或Flux<T>
• 数据库使用 R2DBC（非 JDBC）
• HTTP 调用使用WebClient
• 避免任何阻塞操作
• 使用WebTestClient测试
• 合理处理背压和错误

通过以上指南，你已掌握Spring Boot + WebFlux 的完整开发能力。记住：WebFlux 的价值不在于“更快”，而在于“更高吞吐、更低资源消耗”。在合适的场景下使用它，将显著提升系统伸缩性。

📚 官方文档：

• https://docs.spring.io/spring-framework/docs/current/reference/html/web-reactive.html
• https://r2dbc.io/
• https://projectreactor.io/docs