Spring WebFlux: Reactive Programming with Spring Boot 3 - Real-World Patterns

For over a decade, Spring MVC with Tomcat was the gold standard for building web applications in Java. But as we moved into the era of microservices, IoT, and real-time analytics, the synchronous, thread-per-request model started showing cracks. Each thread consumes roughly 1MB of stack memory, and under high concurrency—say 10,000 concurrent WebSocket connections for a live trading dashboard—you either run out of memory or hit thread-pool limits. Spring WebFlux, introduced in Spring 5 and matured in Spring Boot 3, solves this by embracing reactive programming with Project Reactor. Instead of blocking on I/O, WebFlux uses event loops and backpressure-aware streams (Mono and Flux) to handle thousands of concurrent requests with a handful of threads. This makes it a natural fit for I/O-bound services: API gateways, streaming data pipelines, and payment-processing systems where latency is critical. However, WebFlux is not a drop-in replacement for Spring MVC. It requires a paradigm shift in how you think about data flow, error handling, and even database access. This article walks you through building a reactive REST API with Spring Boot 3, covering real-world patterns for error handling, backpressure, and testing. We'll also dissect a production incident where a naive blocking call brought down a reactive payment service. By the end, you'll understand not just how to use WebFlux, but when and why.

Setting Up a Reactive REST Controller with Mono and Flux

Let's start with a concrete example: a reactive REST API for a payment-processing service that returns a list of transactions and allows creating new ones. In Spring Boot 3, you create a reactive controller using @RestController and return Mono<T> for single items or Flux<T> for streams. The key difference from Spring MVC is that you never return a plain object or ResponseEntity directly—you return a reactive type that the framework subscribes to. Here's a simple controller that fetches transactions from a reactive MongoDB repository. Note that we use Flux<Transaction> for the collection endpoint and Mono<Transaction> for the single-item endpoint. The framework handles the subscription automatically. The real power comes when you combine multiple reactive sources: for example, fetching user details and transaction history concurrently using Mono.zip().

@RestController
@RequestMapping("/api/transactions")
public class TransactionController {

    private final TransactionRepository repository;

    public TransactionController(TransactionRepository repository) {
        this.repository = repository;
    }

    @GetMapping
    public Flux<Transaction> getAllTransactions() {
        return repository.findAll();
    }

    @GetMapping("/{id}")
    public Mono<Transaction> getTransactionById(@PathVariable String id) {
        return repository.findById(id)
                .switchIfEmpty(Mono.error(new ResponseStatusException(HttpStatus.NOT_FOUND, "Transaction not found")));
    }

    @PostMapping
    public Mono<Transaction> createTransaction(@RequestBody Mono<Transaction> transactionMono) {
        return transactionMono.flatMap(repository::save);
    }
}

What the Official Docs Won't Tell You

The official Spring WebFlux documentation is excellent for the happy path, but it glosses over several production realities. First, error handling in reactive streams is fundamentally different from try-catch. You must use onErrorResume(), onErrorReturn(), or doOnError() at the operator level. A single unhandled error in a Flux chain will cancel the entire stream silently—no stack trace, no log, just a cancelled subscription. Second, the documentation doesn't emphasize enough that your entire data access layer must be reactive. If you use spring-boot-starter-data-jpa with WebFlux, you'll block on every database call because JPA is inherently blocking. You need spring-boot-starter-data-r2dbc or reactive MongoDB/Cassandra drivers. Third, backpressure is not automatic—you must configure it explicitly for high-volume streams. For example, when consuming from a Kafka topic via Reactor Kafka, you need to set the prefetch and maxConcurrent values to avoid overwhelming downstream services. Finally, testing reactive code requires StepVerifier from reactor-test, not JUnit's standard assertions. The official docs show basic examples, but in production you'll need virtual time testing with StepVerifier.withVirtualTime() to simulate slow publishers.

Mono<Transaction> transaction = repository.findById("invalid-id")
        .doOnError(e -> log.error("Error fetching transaction", e))
        .onErrorResume(e -> {
            // Fallback: return a cached or default value
            return Mono.just(new Transaction("default", 0.0));
        })
        .onErrorReturn(new Transaction("error", -1.0));

// For Flux, use onErrorContinue() to skip bad items
Flux<Transaction> flux = repository.findAll()
        .onErrorContinue((error, item) -> log.warn("Skipping item {} due to {}", item, error));

Building a Reactive Service Layer with Backpressure

A reactive service layer is where the real magic happens. Let's build a service that processes a stream of transaction events from a message broker (simulated here with a Flux from a list) and applies backpressure. Backpressure is the ability of the consumer to signal to the producer how much data it can handle. In Project Reactor, you control backpressure using operators like limitRate(), buffer(), or by implementing a custom Subscriber. For a payment-processing service, you might want to process transactions in batches of 10 to avoid overwhelming the database. Here's an example that reads a stream of transaction requests, validates them, and saves them in batches. Note the use of .buffer(10) to group items and .flatMapSequential() to maintain order while allowing concurrency. The key insight: without backpressure, a fast producer can flood a slow consumer, causing out-of-memory errors or database connection pool exhaustion.

@Service
public class TransactionService {

    private final TransactionRepository repository;

    public TransactionService(TransactionRepository repository) {
        this.repository = repository;
    }

    public Flux<Transaction> processTransactionStream(Flux<TransactionRequest> requestStream) {
        return requestStream
                .limitRate(50) // Request 50 items at a time from upstream
                .buffer(10)    // Group into batches of 10
                .flatMap(batch -> {
                    // Process batch concurrently, limited to 2 parallel batches
                    return Flux.fromIterable(batch)
                            .flatMap(this::validateAndSave, 2);
                });
    }

    private Mono<Transaction> validateAndSave(TransactionRequest request) {
        if (request.amount() <= 0) {
            return Mono.error(new IllegalArgumentException("Amount must be positive"));
        }
        Transaction tx = new Transaction(request.amount(), request.currency());
        return repository.save(tx);
    }
}

Reactive Data Access with R2DBC and MongoDB

WebFlux is only as reactive as your data layer. Spring Boot 3 provides reactive support for MongoDB (spring-boot-starter-data-mongodb-reactive) and relational databases via R2DBC (spring-boot-starter-data-r2dbc). R2DBC is the reactive alternative to JDBC, supporting PostgreSQL, MySQL, H2, and others. Here's a reactive repository for a PostgreSQL-backed transaction table using R2DBC. Notice that the repository interface extends ReactiveCrudRepository, and methods return Mono or Flux. The key difference from JPA: you cannot use lazy loading or entity graphs—everything is fetched eagerly via reactive streams. Also, transactions must be managed declaratively with @Transactional on reactive methods, but beware: @Transactional in R2DBC works on a reactive transaction manager, not the traditional PlatformTransactionManager. For MongoDB, the reactive driver is even more seamless, supporting reactive repositories out of the box. In production, we prefer MongoDB for purely reactive stacks because it avoids the impedance mismatch of mapping relational tables to reactive streams.

import org.springframework.data.repository.reactive.ReactiveCrudRepository;
import reactor.core.publisher.Flux;

public interface ReactiveTransactionRepository extends ReactiveCrudRepository<Transaction, Long> {

    Flux<Transaction> findByCurrency(String currency);

    @Query("SELECT * FROM transactions WHERE amount > :minAmount")
    Flux<Transaction> findLargeTransactions(double minAmount);
}

// Service usage
@Service
public class TransactionService {
    private final ReactiveTransactionRepository repository;

    public Flux<Transaction> getTransactionsByCurrency(String currency) {
        return repository.findByCurrency(currency);
    }
}

Testing Reactive Endpoints with StepVerifier and WebTestClient

Testing reactive code requires a different mindset. Standard JUnit assertions won't work because Mono and Flux are asynchronous—you need to subscribe to them and assert on the emitted items. Spring provides two key tools: StepVerifier for unit testing reactive streams, and WebTestClient for integration testing reactive controllers. StepVerifier allows you to create a script of expectations: expectNext(), expectComplete(), verifyError(). For time-dependent operators, use StepVerifier.withVirtualTime() to avoid waiting for real time. WebTestClient is a reactive alternative to MockMvc that binds to a WebFlux application context and sends/receives reactive types. Here's a test for the TransactionController we built earlier. Note that we use .exchange() to trigger the request and .expectBody() to assert on the response. For streaming endpoints, use .expectBodyList() or .returnResult() to consume the Flux.

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

    @Autowired
    private WebTestClient webTestClient;

    @MockBean
    private TransactionRepository repository;

    @Test
    void shouldReturnAllTransactions() {
        when(repository.findAll()).thenReturn(Flux.just(
                new Transaction("1", 100.0),
                new Transaction("2", 200.0)
        ));

        webTestClient.get().uri("/api/transactions")
                .exchange()
                .expectStatus().isOk()
                .expectBodyList(Transaction.class)
                .hasSize(2);
    }

    @Test
    void shouldReturn404WhenNotFound() {
        when(repository.findById("999")).thenReturn(Mono.empty());

        webTestClient.get().uri("/api/transactions/999")
                .exchange()
                .expectStatus().isNotFound();
    }

    @Test
    void shouldCreateTransaction() {
        Transaction tx = new Transaction("3", 300.0);
        when(repository.save(any())).thenReturn(Mono.just(tx));

        webTestClient.post().uri("/api/transactions")
                .body(Mono.just(tx), Transaction.class)
                .exchange()
                .expectStatus().isOk()
                .expectBody(Transaction.class)
                .isEqualTo(tx);
    }
}

Combining Multiple Reactive Sources with Zip and Merge

In real-world applications, you often need to combine data from multiple reactive sources. For example, in a payment-processing system, you might need to fetch the user's account balance, the transaction history, and the current exchange rate concurrently, then combine them into a single response. Project Reactor provides several operators for this: Mono.zip() for combining up to 8 Monos into a Tuple, Flux.merge() for interleaving multiple Flux streams, and Flux.concat() for sequential concatenation. Here's an example that fetches user details and recent transactions concurrently using Mono.zip(). The .zip() operator subscribes to all Monos immediately and waits for all to complete before emitting the combined result. This is the reactive equivalent of CompletableFuture.allOf(). For streaming scenarios, Flux.merge() allows you to process events from multiple sources as they arrive, which is ideal for real-time dashboards that aggregate data from Kafka topics.

@Service
public class PaymentService {

    private final UserService userService;
    private final TransactionRepository transactionRepository;
    private final ExchangeRateService exchangeRateService;

    public Mono<PaymentSummary> getPaymentSummary(String userId) {
        Mono<User> userMono = userService.findById(userId);
        Mono<List<Transaction>> transactionsMono = transactionRepository
                .findByUserId(userId)
                .collectList();
        Mono<Double> rateMono = exchangeRateService.getRate("USD", "EUR");

        return Mono.zip(userMono, transactionsMono, rateMono)
                .map(tuple -> {
                    User user = tuple.getT1();
                    List<Transaction> transactions = tuple.getT2();
                    Double rate = tuple.getT3();
                    return new PaymentSummary(user, transactions, rate);
                });
    }

    // For streaming: merge two event streams
    public Flux<Event> mergeEvents(Flux<Event> kafkaEvents, Flux<Event> websocketEvents) {
        return Flux.merge(kafkaEvents, websocketEvents);
    }
}

Handling Timeouts and Retries in Reactive Pipelines

In production, networks fail, databases become slow, and upstream services timeout. Reactive streams provide first-class operators for resilience: timeout(), retry(), and retryWhen(). The timeout() operator raises a TimeoutException if the source doesn't emit within a given duration. retry() resubscribes to the source on error (with a limit to avoid infinite loops). For more sophisticated retry strategies (exponential backoff, jitter), use retryWhen() with a Retry spec. Here's an example that sets a 5-second timeout on a database call and retries up to 3 times with exponential backoff. Note that retry() resubscribes to the original source, so if the source is a cold publisher (like a database query), it will re-execute. For hot publishers (like a WebSocket stream), retry() may not make sense because you'll miss events. Always consider idempotency: if the operation is not idempotent (e.g., inserting a payment), retrying may cause duplicate records. In that case, use a unique request ID to deduplicate on the server side.

import reactor.util.retry.Retry;
import java.time.Duration;

@Service
public class ResilientPaymentService {

    private final PaymentRepository repository;

    public Mono<Payment> processPayment(PaymentRequest request) {
        return repository.save(request.toPayment())
                .timeout(Duration.ofSeconds(5))
                .retryWhen(Retry.backoff(3, Duration.ofMillis(500))
                        .jitter(0.25) // Add 25% jitter to avoid thundering herd
                        .onRetryExhaustedThrow((spec, signal) -> 
                                new RetryExhaustedException("Payment failed after retries", signal.failure()))
                )
                .doOnError(e -> log.error("Payment processing failed after retries", e));
    }
}

Debugging Reactive Streams with Hooks and Logging

Debugging reactive streams is notoriously difficult because stack traces are often unhelpful—errors propagate through the operator chain, and the stack trace shows the assembly point, not the execution point. Project Reactor provides several tools to make debugging easier. First, use Hooks.onOperatorDebug() to enable operator-level debugging, which captures the assembly stack trace for each operator. This adds overhead, so enable it only in development or via a feature flag. Second, use .log() operator to log signals (onNext, onError, onComplete) for a specific part of the pipeline. Third, use .checkpoint() to mark a point in the stream with a description; when an error occurs downstream, the checkpoint appears in the stack trace. Here's an example that uses all three techniques to debug a pipeline that processes transactions. In production, we use a custom logging subscriber that logs at WARN level for errors and DEBUG for normal signals, and we always include a unique request ID in the log context to correlate logs across services.

import reactor.core.publisher.Hooks;
import reactor.core.publisher.Mono;
import reactor.core.publisher.SignalType;
import java.util.logging.Level;

// Enable operator stack traces in dev (add to @PostConstruct or main method)
Hooks.onOperatorDebug();

Mono<Transaction> result = repository.findById(id)
        .checkpoint("Fetch transaction from DB")
        .log("transaction.service", Level.FINE, SignalType.ON_NEXT, SignalType.ON_ERROR)
        .map(tx -> {
            // Simulate a transformation that may fail
            if (tx.amount() < 0) {
                throw new IllegalArgumentException("Negative amount not allowed");
            }
            return tx;
        })
        .checkpoint("After validation")
        .doOnError(e -> log.error("Error processing transaction {}", id, e));

// Subscribe (in real code, the framework does this)
result.subscribe(
    tx -> log.info("Processed: {}", tx),
    error -> log.error("Failed: {}", error)
);