Introduction to Spring WebFlux and Reactive Programming

Spring WebFlux is a reactive programming style web framework introduced in Spring 5, offering non‑blocking I/O and built on the Reactor project. It provides two core APIs, Mono for single‑value streams and Flux for multi‑value streams.

The framework can run on Netty, Undertow, or any Servlet 3.1+ container, and can coexist with Spring MVC in the same project. Reactive programming means that API calls do not block the CPU; instead, the system processes other tasks while waiting for data, improving overall throughput.

When deciding between Spring MVC and Spring WebFlux, consider the following:

If an existing Spring MVC project works well and most third‑party libraries are blocking, staying with MVC is reasonable.

WebFlux offers flexible deployment options (Netty, Tomcat, Jetty, Undertow) and supports functional routing via RouterFunctions or annotation‑based controllers.

For lightweight, functional‑style Java 8 applications or micro‑services that benefit from higher concurrency, WebFlux is recommended.

Both frameworks can share the same @Controller annotations, facilitating mixed‑mode architectures.

Projects heavily using blocking APIs (e.g., JDBC) may not gain much from WebFlux.

Adopting reactive programming has a learning curve; using WebClient can help teams experiment with non‑blocking HTTP calls.

WebFlux’s concurrency model relies on a small number of event‑loop threads (e.g., Netty) instead of a large thread pool used by traditional Servlet containers, leading to higher request throughput.

Typical setup includes adding the dependency:

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

Define a simple data class:

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

Use functional routing instead of @RequestMapping :

@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 corresponding handler processes requests using reactive types:

@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 by default, as confirmed by the startup logs. Accessing http://localhost:8080/person/1 demonstrates a working WebFlux endpoint.