Introduction to Spring WebFlux and Reactive Programming

Spring WebFlux is a reactive‑style web development framework added in Spring 5 that can significantly increase request throughput by leveraging non‑blocking I/O.

Reactive programming means that when an API call is made, the caller does not block waiting for data; instead it is notified when data arrives, allowing the CPU to perform other work and improving overall system throughput.

The framework is built on the Reactor project and provides two core types: Mono for handling a single value and Flux for handling multiple values.

// Mono generally works with a single object
Mono
person = personDao.getPerson(personId);
// Flux generally works with multiple objects
Flux
people = personDao.listAllPeople();

Spring WebFlux can coexist with Spring MVC, but choosing between them depends on factors such as existing blocking libraries, desired programming style, and the need for high concurrency. The official guidance suggests keeping MVC if the current project works well, using WebFlux for lightweight or functional‑style services, and mixing both in micro‑service architectures when appropriate.

In terms of concurrency, Spring MVC uses a thread‑per‑request model with a fixed thread pool, which limits throughput due to blocking I/O. WebFlux, by contrast, runs on non‑blocking servers like Netty and requires only a few event‑loop threads, allowing the CPU to be utilized more efficiently.

Below is a minimal Maven dependency required to enable WebFlux in a Spring Boot project:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

A simple Person domain class:

public class Person {
    private Integer id;
    private Integer age;
    private String name;
}

The routing configuration uses functional style instead of the traditional @RequestMapping annotation:

@Configuration
public class PersonRouter {
    @Resource
    private PersonHandler personHandler;

    @Bean
    public RouterFunction
personRoutes() {
        return RouterFunctions.route()
            .GET("/person/{id}", RequestPredicates.accept(MediaType.APPLICATION_JSON), personHandler::getPerson)
            .GET("/person", RequestPredicates.accept(MediaType.APPLICATION_JSON), personHandler::listPeople)
            .POST("/person", personHandler::createPerson)
            .build();
    }
}

The handler implements the reactive endpoints, returning Mono or Flux wrapped in ServerResponse objects:

@Component
public class PersonHandler {
    @Resource
    private PersonRepository personDao;

    public Mono
listPeople(ServerRequest request) {
        Flux
people = personDao.listAllPeople();
        return ServerResponse.ok()
            .contentType(MediaType.APPLICATION_JSON)
            .body(people, Person.class);
    }

    public Mono
createPerson(ServerRequest request) {
        Mono
person = request.bodyToMono(Person.class);
        return ServerResponse.ok().build(personDao.savePerson(person));
    }

    public Mono
getPerson(ServerRequest request) {
        int personId = Integer.parseInt(request.pathVariable("id"));
        return personDao.getPerson(personId)
            .flatMap(p -> ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).bodyValue(p))
            .switchIfEmpty(ServerResponse.notFound().build());
    }
}

When the application starts, Spring Boot uses Netty as the default server; accessing http://localhost:8080/person/1 demonstrates that the WebFlux service is running correctly.