Non-blocking I/O with Spring WebFlux

In today's fast-paced digital world, applications need to handle a massive number of concurrent user requests efficiently. Traditional, blocking I/O approaches often struggle to meet these demands. This is where non-blocking I/O comes into play, allowing applications to handle multiple requests concurrently without locking the execution.

Spring WebFlux, a part of the Spring Framework 5, provides a reactive programming model for building web applications. It enables developers to leverage the power of non-blocking I/O and create highly scalable and responsive applications. Let's take a closer look at how Spring WebFlux achieves this non-blocking behavior.

Understanding Non-blocking I/O

In a traditional blocking I/O approach, a thread is assigned to each incoming request. If a thread is busy processing a request, it remains blocked until the processing completes. During this time, the thread cannot be used to handle other requests. This approach works well for a small number of concurrent users but faces serious scalability issues as the number of users increases.

Non-blocking I/O, on the other hand, allows a single thread to handle multiple requests concurrently. When a request arrives, it is assigned to a thread, and if the thread encounters I/O operations, it doesn't block and gets assigned to another task while the I/O operation completes in the background. This allows the thread to handle other tasks in the meantime, resulting in efficient utilization of system resources.

Spring WebFlux and Reactor

Spring WebFlux is built on top of Project Reactor, a reactive programming library that provides the core capabilities for non-blocking applications. Reactor is based on the Reactive Streams specification, which defines a standard for asynchronous stream processing with non-blocking back pressure.

Using Reactor, Spring WebFlux provides two programming models: Annotated Controllers and Functional Endpoints. Both models allow developers to build non-blocking I/O applications using familiar Spring concepts.

Annotated Controllers with Spring WebFlux

Annotated Controllers in Spring WebFlux are similar to traditional Spring MVC controllers, but they are built using reactive programming techniques. To create a non-blocking endpoint, you can use the @RestController annotation and leverage Reactor types, such as Mono and Flux, to handle the response.

Here's an example of a simple non-blocking controller using Spring WebFlux:

public class UserController {

    private UserService userService;

    public Mono<User> getUserById(@PathVariable String id) {
        return userService.getUserById(id);

    public Flux<User> getAllUsers() {
        return userService.getAllUsers();

    // Other endpoints...


In the above example, the getUserById method returns a Mono<User>, representing a single user. The getAllUsers method returns a Flux<User>, representing a stream of users. These reactive types allow the methods to handle multiple concurrent requests efficiently.

Functional Endpoints with Spring WebFlux

Functional Endpoints is another approach provided by Spring WebFlux to define non-blocking APIs. This approach leverages Java 8 lambdas and functional programming to define routes and request handlers.

Here's an example of a functional endpoint using Spring WebFlux:

public class UserRouter {

    private UserService userService;

    public RouterFunction<ServerResponse> userRoutes() {
        return RouterFunctions.route()
                .GET("/users/{id}", request -> ServerResponse.ok()
                        .body(userService.getUserById(request.pathVariable("id")), User.class))
                .GET("/users", request -> ServerResponse.ok()
                        .body(userService.getAllUsers(), User.class))
                // Other routes...


In this example, we define routes using lambda expressions and handle requests asynchronously using the reactive types.


Spring WebFlux provides an excellent foundation for building non-blocking I/O applications with ease. By leveraging the power of Project Reactor, developers can create highly scalable and responsive applications that can handle a massive number of concurrent requests efficiently. Whether you choose to use Annotated Controllers or Functional Endpoints, Spring WebFlux provides the flexibility and power required for non-blocking I/O.

noob to master © copyleft