Spring WebFlux is Spring’s reactive-stack web framework, designed for building non-blocking, asynchronous, and scalable web applications. Unlike traditional Spring MVC, which uses a thread-per-request model, WebFlux handles requests reactively, making it ideal for modern cloud-native, event-driven architectures where efficiency and scalability are critical.
In this article, you’ll learn how to build non-blocking REST services with Spring WebFlux and Project Reactor, along with practical examples and best practices.
Why Use Spring WebFlux?
Traditional synchronous systems work fine for low to medium workloads, but under heavy load, thread exhaustion becomes a serious problem. Reactive programming provides a non-blocking execution model, which allows you to:
- Handle massive concurrency with fewer threads.
- Improve resource utilization (CPU, memory, I/O).
- Develop highly responsive APIs, even under pressure.
If you’re building systems like real-time streaming platforms, IoT backends, or microservices at scale, WebFlux is worth mastering.
Further Reading: Official Spring WebFlux Documentation
Core Components of Spring WebFlux
Spring WebFlux is built on top of Project Reactor, Spring’s reactive library that implements the Reactive Streams specification.
Key Types in Reactor:
- Mono<T>: Represents 0 or 1 element.
- Flux<T>: Represents 0 to N elements (a stream).
These types replace Future and List in asynchronous programming, enabling powerful data pipelines with map, flatMap, filter, and zip operations.
Setting Up a Spring WebFlux Project
You can start by creating a Spring Boot project using Spring Initializr.
Dependencies:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
You can also add reactor-test for testing reactive streams.
Building a Simple Reactive REST API
Let’s create a simple Product API.
Product Model:
public record Product(String id, String name, double price) {}
Reactive Repository (Simulated with Flux):
For demo purposes, we can simulate data using Flux:
@RestController
@RequestMapping("/products")
public class ProductController {
private static final List<Product> products = List.of(
new Product("1", "Laptop", 999.99),
new Product("2", "Phone", 499.99),
new Product("3", "Tablet", 299.99)
);
@GetMapping
public Flux<Product> getAllProducts() {
return Flux.fromIterable(products);
}
@GetMapping("/{id}")
public Mono<ResponseEntity<Product>> getProductById(@PathVariable String id) {
return Mono.justOrEmpty(
products.stream()
.filter(p -> p.id().equals(id))
.findFirst()
).map(ResponseEntity::ok)
.defaultIfEmpty(ResponseEntity.notFound().build());
}
}
Non-Blocking I/O in Action
Unlike @RestController in Spring MVC, WebFlux controllers return Mono or Flux, signaling asynchronous, non-blocking data flows.
Under the hood, Spring uses Netty (via Reactor Netty) instead of Tomcat.
Functional Endpoints vs Annotated Controllers
WebFlux supports functional routing too:
@Bean
public RouterFunction<ServerResponse> route() {
return RouterFunctions.route()
.GET("/hello", request -> ServerResponse.ok().bodyValue("Hello, Reactive World!"))
.build();
}
This approach is inspired by functional programming paradigms, making your APIs more composable and testable.
Streaming with Server-Sent Events (SSE)
WebFlux makes real-time data streaming easy. Here’s an example of SSE:
@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamEvents() {
return Flux.interval(Duration.ofSeconds(1))
.map(seq -> "Event: " + seq);
}
Learn More: Server-Sent Events with Spring
Error Handling in WebFlux
Use .onErrorResume() and .doOnError() for reactive error handling:
@GetMapping("/error-example")
public Mono<String> errorExample() {
return Mono.error(new RuntimeException("Something went wrong"))
.onErrorResume(ex -> Mono.just("Fallback response"));
}
For global exception handling, use @ControllerAdvice with @ExceptionHandler.
Performance Benefits of WebFlux
Spring WebFlux excels when:
- Concurrent connections are high (e.g., 10,000+ concurrent HTTP clients).
- Backend services are I/O bound (e.g., database calls, remote APIs).
- You need real-time data streaming.
However, for CPU-bound workloads, the benefits may be limited because reactive systems don’t magically speed up computations—they optimize I/O handling.
Benchmark Comparison: See the TechEmpower Framework Benchmarks for performance comparisons between WebFlux, Spring MVC, and other frameworks.
Testing Reactive APIs
Use StepVerifier from reactor-test to test Flux and Mono streams:
@Test
void testGetAllProducts() {
Flux productFlux = controller.getAllProducts();
StepVerifier.create(productFlux)
.expectNextCount(3)
.verifyComplete();
}
For Web testing, use WebTestClient:
@Autowired
private WebTestClient webTestClient;
@Test
void testProductApi() {
webTestClient.get().uri("/products")
.exchange()
.expectStatus().isOk()
.expectBodyList(Product.class).hasSize(3);
}
When Should You Use WebFlux?
Use Spring WebFlux when:
- You need to handle large-scale concurrent connections.
- Your system is I/O bound, not CPU bound.
- You’re building real-time applications (chat, notifications, stock tickers).
Stick with Spring MVC when:
- Your team is more comfortable with imperative programming.
- You’re dealing with traditional blocking databases (like JDBC without R2DBC).
Conclusion
Spring WebFlux is a powerful toolkit for building scalable, non-blocking REST APIs. By leveraging Project Reactor and the reactive programming paradigm, you can handle thousands of concurrent requests with fewer resources.
Summary of Benefits:
- Non-blocking
- Scalable under load
- Real-time streaming support
- Easy integration with Reactor and Kotlin Coroutines
Further Learning & References
