Spring WebFlux: A Practical Guide for Java Developers

Paritosh Gautam — Wed, 30 Sep 2026 15:48:09 +0000

1. Introduction — Why Does WebFlux Exist?

If you've built REST APIs with Spring MVC, you know the model: one thread handles one request, start to finish. That thread blocks while waiting for a database call, a downstream HTTP call, or a file read. This is called the thread-per-request model, and it works fine — until you have thousands of concurrent, slow, I/O-heavy requests. At that point, you run out of threads, not CPU.

Spring WebFlux solves this by using a reactive, non-blocking model. Instead of a thread waiting for an I/O operation to finish, the thread is freed up immediately, and a callback resumes the work when the data is ready. A small, fixed number of threads (often just as many as CPU cores) can then handle a huge number of concurrent requests.

Key idea: WebFlux doesn't make your code faster for a single request. It makes your server handle more concurrent requests using fewer threads, especially when those requests spend most of their time waiting on I/O.

Before you adopt it, understand the tradeoff:

Traditional Spring MVC: simple to write, simple to debug, but scales concurrency by adding threads (which are expensive — each has its own stack, ~1MB by default).
Spring WebFlux: scales concurrency with a handful of threads, but the programming style (functional, asynchronous, chained) is harder to read and debug, especially stack traces.

2. Reactive Programming Basics: The Reactive Streams Specification

WebFlux is built on the Reactive Streams specification, a standard for asynchronous stream processing with non-blocking backpressure. It defines four interfaces:

public interface Publisher<T> {
    void subscribe(Subscriber<? super T> s);
}

public interface Subscriber<T> {
    void onSubscribe(Subscription s);
    void onNext(T t);
    void onError(Throwable t);
    void onComplete();
}

public interface Subscription {
    void request(long n);
    void cancel();
}

public interface Processor<T, R> extends Subscriber<T>, Publisher<R> {
}

In plain English:

A Publisher produces a stream of data over time (e.g., rows from a database, or messages from a queue).
A Subscriber consumes that data.
A Subscription is the contract between them — the Subscriber calls request(n) to say "send me n items," which is how backpressure is implemented (the consumer controls the pace, so it's never overwhelmed).

You will rarely implement these interfaces directly. Instead, you'll use Project Reactor, the reactive library Spring builds on top of these interfaces.

3. Project Reactor: Mono and Flux

Reactor gives you two core types, both of which implement Publisher<T>:

Mono<T> — represents 0 or 1 result (like a reactive Optional<T> or a CompletableFuture<T>).
Flux<T> — represents 0 to N results (like a reactive Stream<T> or List<T>, but emitted over time).

Creating a Mono

Mono<String> mono = Mono.just("Hello, WebFlux");

Mono<String> emptyMono = Mono.empty();

Mono<String> fromCallable = Mono.fromCallable(() -> {
    // some computation
    return "computed value";
});

Creating a Flux

Flux<Integer> flux = Flux.just(1, 2, 3, 4, 5);

Flux<Integer> range = Flux.range(1, 10);

Flux<String> fromList = Flux.fromIterable(List.of("a", "b", "c"));

Nothing Happens Until You Subscribe

This is the single most important concept in Reactor. Mono and Flux are lazy — declaring one does not execute anything. Nothing runs until a Subscriber subscribes.

Mono<String> mono = Mono.fromCallable(() -> {
    System.out.println("This runs only on subscribe");
    return "data";
});

// Nothing printed yet

mono.subscribe(value -> System.out.println("Got: " + value));
// Now "This runs only on subscribe" and "Got: data" are printed

In a Spring WebFlux controller, you never call .subscribe() yourself — the framework does that for you when it processes the HTTP response. If you write code that never gets subscribed to, it simply never runs, silently. This is the most common beginner mistake.

Chaining Operators

Reactor's power comes from chaining operators that transform the stream. A few essentials:

Flux<Integer> numbers = Flux.range(1, 5);

Flux<Integer> doubled = numbers.map(n -> n * 2);          // transform each element
Flux<Integer> evens = numbers.filter(n -> n % 2 == 0);    // keep only matching elements

Flux<String> names = Flux.just("alice", "bob");
Mono<List<String>> asList = names.collectList();          // Flux -> Mono<List<T>>

// flatMap: for each element, call something else that returns a Mono/Flux, and flatten the result
Flux<Order> orders = Flux.just("user1", "user2")
        .flatMap(userId -> orderService.getOrdersForUser(userId)); // returns Flux<Order>

map vs flatMap is the same distinction as in Java Streams: use map for synchronous, one-to-one transformations; use flatMap when the transformation itself returns a Mono/Flux (e.g., another async call).

Combining Streams

Mono<User> userMono = userService.findById(id);
Mono<List<Order>> ordersMono = orderService.findByUserId(id).collectList();

Mono<UserProfile> profile = Mono.zip(userMono, ordersMono)
        .map(tuple -> new UserProfile(tuple.getT1(), tuple.getT2()));

Mono.zip waits for both sources to complete and combines their results — useful when you need data from two independent async sources.

4. Setting Up a Spring WebFlux Project

Add the WebFlux starter to your pom.xml (Maven):

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

Or Gradle:

implementation 'org.springframework.boot:spring-boot-starter-webflux'

Important: Do not include both spring-boot-starter-web (Spring MVC) and spring-boot-starter-webflux in the same application unless you specifically know you want a mixed setup — Spring Boot will auto-configure MVC by default if both are on the classpath, silently defeating your reactive setup.

By default, WebFlux runs on Netty (an async, event-loop-based server), not Tomcat. This is what actually gives you the non-blocking I/O — WebFlux code on a blocking servlet container still benefits from fewer threads for request handling, but Netty is the natural fit.

5. The Annotation-Based Programming Model

The good news: if you know @RestController, you already know 80% of WebFlux's annotation model. The main difference is your return types become Mono<T> and Flux<T> instead of T and List<T>.

Traditional Spring MVC (blocking)

@RestController
@RequestMapping("/users")
public class UserController {

    private final UserRepository userRepository;

    public UserController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @GetMapping("/{id}")
    public User getUser(@PathVariable String id) {
        return userRepository.findById(id).orElseThrow();
    }

    @GetMapping
    public List<User> getAllUsers() {
        return userRepository.findAll();
    }
}

Spring WebFlux (non-blocking)

@RestController
@RequestMapping("/users")
public class UserController {

    private final UserRepository userRepository;

    public UserController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @GetMapping("/{id}")
    public Mono<User> getUser(@PathVariable String id) {
        return userRepository.findById(id);
    }

    @GetMapping
    public Flux<User> getAllUsers() {
        return userRepository.findAll();
    }

    @PostMapping
    public Mono<User> createUser(@RequestBody Mono<User> userMono) {
        return userMono.flatMap(userRepository::save);
    }
}

Notice createUser accepts Mono<User> as the request body itself — the deserialization of the incoming JSON is also non-blocking, and chained with flatMap once the body arrives.

Streaming a Flux as Server-Sent Events

One of WebFlux's superpowers is trivially streaming data to a client as it becomes available:

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<Tick> streamTicks() {
    return Flux.interval(Duration.ofSeconds(1))
            .map(seq -> new Tick(seq, Instant.now()));
}

This endpoint keeps the HTTP connection open and pushes a new Tick every second — no polling required from the client. Doing this in Spring MVC requires much more manual plumbing (e.g., SseEmitter with a background thread).

6. Functional Endpoints (The Alternative to `@RestController`)

WebFlux also offers a functional programming model as an alternative to annotations. Instead of annotating methods, you explicitly wire routes to handler functions. This is more verbose but gives you full control and is easier to unit test in isolation.

// Handler
@Component
public class UserHandler {

    private final UserRepository userRepository;

    public UserHandler(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public Mono<ServerResponse> getUser(ServerRequest request) {
        String id = request.pathVariable("id");
        return userRepository.findById(id)
                .flatMap(user -> ServerResponse.ok().bodyValue(user))
                .switchIfEmpty(ServerResponse.notFound().build());
    }

    public Mono<ServerResponse> getAllUsers(ServerRequest request) {
        Flux<User> users = userRepository.findAll();
        return ServerResponse.ok()
                .contentType(MediaType.APPLICATION_JSON)
                .body(users, User.class);
    }
}

// Router configuration
@Configuration
public class UserRouter {

    @Bean
    public RouterFunction<ServerResponse> routes(UserHandler handler) {
        return RouterFunctions.route()
                .GET("/users/{id}", handler::getUser)
                .GET("/users", handler::getAllUsers)
                .build();
    }
}

You don't need to choose one style exclusively — a real project can mix @RestController endpoints and functional routes. Most teams pick annotations for simplicity and use functional endpoints only where fine-grained control is needed.

7. WebClient — The Reactive HTTP Client

If your service calls other services over HTTP, use WebClient instead of the old, blocking RestTemplate (which is now in maintenance mode). WebClient is fully non-blocking.

Basic setup

@Configuration
public class WebClientConfig {

    @Bean
    public WebClient webClient(WebClient.Builder builder) {
        return builder
                .baseUrl("https://api.example.com")
                .build();
    }
}

Making calls

@Service
public class OrderClient {

    private final WebClient webClient;

    public OrderClient(WebClient webClient) {
        this.webClient = webClient;
    }

    public Mono<Order> getOrder(String orderId) {
        return webClient.get()
                .uri("/orders/{id}", orderId)
                .retrieve()
                .bodyToMono(Order.class);
    }

    public Flux<Order> getAllOrders() {
        return webClient.get()
                .uri("/orders")
                .retrieve()
                .bodyToFlux(Order.class);
    }

    public Mono<Order> createOrder(Order newOrder) {
        return webClient.post()
                .uri("/orders")
                .bodyValue(newOrder)
                .retrieve()
                .bodyToMono(Order.class);
    }
}

Handling error responses

public Mono<Order> getOrder(String orderId) {
    return webClient.get()
            .uri("/orders/{id}", orderId)
            .retrieve()
            .onStatus(HttpStatusCode::is4xxClientError,
                    response -> Mono.error(new OrderNotFoundException(orderId)))
            .onStatus(HttpStatusCode::is5xxServerError,
                    response -> Mono.error(new UpstreamServiceException()))
            .bodyToMono(Order.class);
}

Calling multiple services in parallel

Because WebClient calls are non-blocking, you can trivially fan out calls concurrently:

public Mono<Dashboard> buildDashboard(String userId) {
    Mono<User> userMono = userClient.getUser(userId);
    Mono<List<Order>> ordersMono = orderClient.getAllOrders(userId).collectList();
    Mono<Recommendations> recsMono = recommendationClient.getRecommendations(userId);

    return Mono.zip(userMono, ordersMono, recsMono)
            .map(tuple -> new Dashboard(tuple.getT1(), tuple.getT2(), tuple.getT3()));
}

All three HTTP calls fire at roughly the same time; zip waits for all to complete. This is much cleaner than manually orchestrating threads or CompletableFuture.allOf.

8. Reactive Data Access

Traditional JDBC and JPA are blocking — they'll block a thread waiting on the database, defeating the purpose of WebFlux. To keep the whole chain non-blocking end-to-end, you need a reactive data layer.

Options

R2DBC (Reactive Relational Database Connectivity) — for relational databases like PostgreSQL, MySQL, SQL Server.
Reactive MongoDB — via spring-boot-starter-data-mongodb-reactive.
Reactive Redis — via spring-boot-starter-data-redis-reactive.

Example: R2DBC repository

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-r2dbc</artifactId>
</dependency>
<dependency>
    <groupId>io.r2dbc</groupId>
    <artifactId>r2dbc-postgresql</artifactId>
</dependency>

public interface UserRepository extends ReactiveCrudRepository<User, String> {

    Flux<User> findByLastName(String lastName);

    @Query("SELECT * FROM users WHERE age > :age")
    Flux<User> findUsersOlderThan(int age);
}

This looks almost identical to a JpaRepository, but every method returns Mono or Flux, and under the hood, the driver never blocks a thread waiting for the database.

Critical rule: If you use WebFlux with a blocking data layer (plain JDBC, standard JPA/Hibernate), you have defeated the purpose. You'll block the small number of event-loop threads, and your app will perform worse than a traditional blocking MVC app under load. Either go fully reactive (R2DBC) or don't use WebFlux at all for that service — see Section 12.

9. Error Handling

Reactor gives you dedicated operators for error handling, analogous to try/catch but for async streams.

public Mono<User> getUser(String id) {
    return userRepository.findById(id)
            .switchIfEmpty(Mono.error(new UserNotFoundException(id)))
            .onErrorResume(DataAccessException.class, ex -> {
                log.error("Database error while fetching user {}", id, ex);
                return Mono.error(new ServiceUnavailableException());
            })
            .doOnError(ex -> log.warn("Failed to fetch user {}: {}", id, ex.getMessage()));
}

switchIfEmpty — supplies an alternative (often an error) when the source is empty.
onErrorResume — catches an error and lets you return a fallback Mono/Flux, or a translated error.
onErrorReturn — catches an error and returns a plain fallback value.
doOnError — a side-effect hook (e.g., logging) that doesn't change the stream.

Global exception handling

Just like @ControllerAdvice in Spring MVC, WebFlux supports the same annotation, applied to reactive return types:

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(UserNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(new ErrorResponse(ex.getMessage()));
    }
}

Spring unwraps the error from the Mono/Flux and routes it to the matching @ExceptionHandler, exactly as it would for a synchronous exception in MVC.

10. Backpressure

Backpressure is the mechanism that stops a fast producer from overwhelming a slow consumer. Recall from Section 2: the Subscriber calls request(n) to control how many items it wants.

In practice, you rarely manage this manually — Reactor and Spring handle it for you (e.g., WebFlux naturally paces database reads to match how fast an HTTP client can consume a streamed response). But you should know it exists, and you can influence it:

Flux.range(1, 1000)
    .onBackpressureDrop(dropped -> log.warn("Dropped: {}", dropped))
    .subscribe(value -> process(value));

Common strategies when a producer is faster than a consumer:

onBackpressureBuffer() — queue excess items in memory (risk: OutOfMemoryError if unbounded).
onBackpressureDrop() — silently discard items that can't be handled in time.
onBackpressureLatest() — keep only the most recent item, drop the rest.

For typical CRUD-style REST APIs, you won't need to configure this explicitly. It becomes relevant for high-throughput streaming pipelines (e.g., ticking market data, log aggregation, IoT sensor feeds).

11. Testing WebFlux Code

Unit-testing reactive types with `StepVerifier`

Reactor provides StepVerifier to assert the sequence of events emitted by a Mono/Flux.

@Test
void shouldReturnUserById() {
    Mono<User> userMono = userService.getUser("123");

    StepVerifier.create(userMono)
            .expectNextMatches(user -> user.getId().equals("123"))
            .verifyComplete();
}

@Test
void shouldReturnErrorForMissingUser() {
    Mono<User> userMono = userService.getUser("unknown");

    StepVerifier.create(userMono)
            .expectError(UserNotFoundException.class)
            .verify();
}

@Test
void shouldStreamMultipleOrders() {
    Flux<Order> orders = orderService.getAllOrders();

    StepVerifier.create(orders)
            .expectNextCount(3)
            .verifyComplete();
}

Integration-testing controllers with `WebTestClient`

WebTestClient is the reactive equivalent of MockMvc.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserControllerTest {

    @Autowired
    private WebTestClient webTestClient;

    @Test
    void shouldReturnUser() {
        webTestClient.get()
                .uri("/users/123")
                .exchange()
                .expectStatus().isOk()
                .expectBody(User.class)
                .value(user -> assertThat(user.getId()).isEqualTo("123"));
    }

    @Test
    void shouldReturnAllUsers() {
        webTestClient.get()
                .uri("/users")
                .exchange()
                .expectStatus().isOk()
                .expectBodyList(User.class)
                .hasSize(2);
    }
}

12. WebFlux vs Spring MVC — When to Use Which

This is the most important decision, and many teams get it wrong by adopting WebFlux everywhere out of hype. A simple decision guide:

Use Spring MVC (blocking) when:

Your app is mostly CPU-bound, or does simple CRUD with a small number of concurrent users.
You depend on blocking libraries (traditional JDBC drivers, blocking clients) that you can't or don't want to replace.
Your team values simplicity, easy debugging, and straightforward stack traces over raw scalability.
This covers the vast majority of internal business applications.

Use Spring WebFlux (reactive) when:

You need to handle a very high number of concurrent connections with limited threads/memory (e.g., API gateways, streaming services, high-throughput proxies).
Your workload is I/O-bound: lots of calls to other services, databases, or message queues, where threads would otherwise sit idle waiting.
You're building a streaming API (Server-Sent Events, WebSocket-like behavior).
Your entire stack — from HTTP client, to business logic, to the database driver — can be made non-blocking. A reactive front layer on top of blocking JDBC gives you the worst of both worlds.

Rule of thumb: don't reach for WebFlux just because it's newer. It solves a specific scalability problem (many concurrent, slow, I/O-bound requests) at the cost of code complexity. If you don't have that problem, Spring MVC is usually the better choice.

13. Common Pitfalls

Blocking inside a reactive chain. Calling a blocking method (e.g., Thread.sleep(), a JDBC call, or .block()) inside a map/flatMap freezes one of your few event-loop threads, which can stall your entire application under load.
```
// BAD — blocks the event loop thread
Mono<User> getUser(String id) {
    return Mono.fromCallable(() -> jdbcTemplate.queryForObject(...)); 
    // still blocking, just deferred — wrong fix
}
```
The correct fix is to use a genuinely non-blocking driver (R2DBC), or if you absolutely must call blocking code, offload it explicitly:
```
Mono<User> getUser(String id) {
    return Mono.fromCallable(() -> legacyBlockingDao.findById(id))
            .subscribeOn(Schedulers.boundedElastic());
}
```
Schedulers.boundedElastic() is a thread pool designed specifically for wrapping blocking calls safely, keeping them off the main event-loop threads.
Calling .block() in production code. .block() converts a Mono/Flux back into a synchronous value — but it also blocks the calling thread, defeating the whole point of WebFlux. It's fine in tests or main() methods, never in request-handling code.
Forgetting that nothing runs without a subscriber. If you write a chain of operators but never return it from a controller method (or otherwise subscribe to it), it silently does nothing — no exception, no log, just missing behavior.
Mixing spring-boot-starter-web and spring-boot-starter-webflux. As mentioned in Section 4, pick one.
Debugging pain. Stack traces in reactive code often show Reactor's internals rather than your business logic's call path. Add .checkpoint("meaningful description") at key points in a chain during development to get better error context, and consider enabling Reactor's Hooks.onOperatorDebug() (only in development — it has a performance cost) to get full assembly traces.

14. A Complete, Minimal Example

Putting it together — a small WebFlux service backed by R2DBC:

// Entity
public record User(@Id String id, String name, int age) {}

// Repository
public interface UserRepository extends ReactiveCrudRepository<User, String> {
    Flux<User> findByAgeGreaterThan(int age);
}

// Service
@Service
public class UserService {

    private final UserRepository repository;

    public UserService(UserRepository repository) {
        this.repository = repository;
    }

    public Mono<User> getUser(String id) {
        return repository.findById(id)
                .switchIfEmpty(Mono.error(new UserNotFoundException(id)));
    }

    public Flux<User> getAdults() {
        return repository.findByAgeGreaterThan(17);
    }

    public Mono<User> createUser(User user) {
        return repository.save(user);
    }
}

// Controller
@RestController
@RequestMapping("/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{id}")
    public Mono<User> getUser(@PathVariable String id) {
        return userService.getUser(id);
    }

    @GetMapping("/adults")
    public Flux<User> getAdults() {
        return userService.getAdults();
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Mono<User> createUser(@RequestBody Mono<User> user) {
        return user.flatMap(userService::createUser);
    }
}

// Global error handling
@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleNotFound(UserNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

This is a fully non-blocking path: HTTP request → controller → service → R2DBC repository → database, and back, without a single thread ever waiting idly on I/O.

15. Summary

Concept	Spring MVC	Spring WebFlux
Model	Thread-per-request, blocking	Event-loop, non-blocking
Return types	`T`, `List<T>`	`Mono<T>`, `Flux<T>`
HTTP client	`RestTemplate`	`WebClient`
Server	Tomcat (typically)	Netty (typically)
Data access	JDBC / JPA	R2DBC / Reactive drivers
Testing	`MockMvc`	`WebTestClient`
Best for	CPU-bound, simple CRUD, small-to-medium concurrency	I/O-bound, high-concurrency, streaming

Key takeaways:

Mono/Flux are lazy — nothing runs without a subscriber.
Chain, don't block — use map/flatMap instead of extracting values early.
Go reactive end-to-end, or not at all — a reactive controller over a blocking database call is a trap.
Adopt WebFlux for a concrete scalability need, not because it's the newer API.

With these fundamentals, you have what you need to read, write, and reason about real Spring WebFlux codebases.

This article was created with the help of AI & online articles.

DEV Community: Paritosh Gautam