From Blocking Threads to Million‑Request Reactive Architecture: A Spring WebFlux Practical Guide

Blocking problem in traditional Spring MVC

In the synchronous servlet model each request occupies a thread while waiting for I/O (database, remote calls). Under high concurrency this leads to thread‑pool exhaustion and latency spikes.

Asynchronous non‑blocking model of Spring WebFlux

WebFlux is built on the Reactor library and an event‑driven callback mechanism. After issuing an I/O request the thread is released immediately and can serve other work; the response is emitted when the I/O completes.

Performance evidence

A 2025 academic study measured a streaming‑media service. WebFlux responded in 0.84 ms while the same workload on Spring MVC took 3414 ms , showing a dramatic latency reduction.

Core reactive concepts (the “three pillars”)

Non‑blocking I/O : threads are free while waiting for data.

Asynchronous data streams : HTTP requests, database calls and other operations are treated as streams that can be processed declaratively.

Backpressure : a consumer can signal the producer to slow down, preventing unbounded memory growth.

Reactive types provided by Reactor

Mono<T>

– a sequence that emits zero or one element (e.g., fetching a single user). Flux<T> – a sequence that emits zero to many elements (e.g., streaming all users or server‑sent events).

Comparison: Spring MVC vs Spring WebFlux

Programming model : MVC is synchronous‑blocking; WebFlux is asynchronous‑non‑blocking.

Core dependency : MVC relies on the Servlet API; WebFlux uses Reactor (Mono/Flux).

Thread model : MVC allocates one thread per request; WebFlux runs on an event‑loop where a few threads handle thousands of connections.

Typical servers : MVC runs on Tomcat/Jetty; WebFlux runs on Netty (or Undertow) which supports non‑blocking I/O.

Suitable scenarios : MVC fits low‑concurrency CRUD apps; WebFlux excels at high‑concurrency, low‑latency, real‑time streams and I/O‑intensive services.

Practical setup

Add the WebFlux starter to a Spring Boot project. Netty is used by default.

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

Annotation‑based controller (closest to MVC)

@RestController
@RequestMapping("/api/users")
public class UserController {
    private final UserService userService;
    public UserController(UserService userService) { this.userService = userService; }

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

    @GetMapping
    public Flux<User> getUsers() {
        return userService.findAll();
    }

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

Functional endpoint (lighter, more flexible)

@Component
public class UserHandler {
    private final UserService userService;
    public Mono<ServerResponse> getUserById(ServerRequest request) {
        String id = request.pathVariable("id");
        return userService.findById(id)
                .flatMap(user -> ServerResponse.ok().bodyValue(user))
                .switchIfEmpty(ServerResponse.notFound().build());
    }
    public Mono<ServerResponse> getUsers(ServerRequest request) {
        return ServerResponse.ok().body(userService.findAll(), User.class);
    }
}

@Configuration
public class UserRouter {
    @Bean
    public RouterFunction<ServerResponse> userRoutes(UserHandler handler) {
        return RouterFunctions.route()
                .GET("/api/func/users/{id}", handler::getUserById)
                .GET("/api/func/users", handler::getUsers)
                .POST("/api/func/users", handler::createUser)
                .build();
    }
}

Deep integration: R2DBC for reactive database access

Add the R2DBC starter and the PostgreSQL driver.

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

Configuration (application.yml):

spring:
  r2dbc:
    url: r2dbc:postgresql://localhost:5432/mydb
    username: admin
    password: pass
    pool:
      max-size: 10

Entity and repository:

@Table("users")
public class User {
    @Id
    private Long id;
    private String name;
    // getters/setters omitted
}

public interface UserRepository extends ReactiveCrudRepository<User, Long> { }

Performance observations

2025 research shows WebFlux + NoSQL reduces average response time by ~50 % compared with RDBMS.

When concurrent users exceed 5 000, the WebFlux + NoSQL combination outperforms traditional setups.

Under extreme load (≈1 000 concurrent) memory usage can increase (possible OOM), but thread utilisation improves dramatically while CPU usage stays comparable to MVC.

Common pitfalls

Blocking trap : never call blocking APIs (e.g., Thread.sleep(), JDBC) inside a reactive flow.

Error handling : use operators such as onErrorResume or onErrorReturn to keep the stream alive.

Testing : employ WebTestClient, which is designed for reactive endpoints.

Thread model: Servlet vs Netty event‑loop

Servlet model: request → Tomcat thread pool → controller → JDBC → block → response.

WebFlux runs on Netty with an event‑loop model where a small number of threads (typically CPU cores × 2) handle tens of thousands of concurrent connections.

Reactor execution flow

Mono.just("hello")
    .map(v -> v + " world")
    .map(String::toUpperCase)
    .subscribe(System.out::println);

// Underlying flow: Publisher → Operator → Subscriber

Backpressure (Reactive Streams specification)

When a producer emits 10 000 items per second but the consumer can handle only 100, backpressure limits the emission to avoid memory explosion.

Flux.range(1, 1000)
    .limitRate(10)
    .subscribe(System.out::println);

Schedulers (thread pools)

immediate

: current thread. single: single‑threaded. parallel: CPU‑bound work. boundedElastic: for blocking tasks.

Example: run a blocking JDBC call on a boundedElastic scheduler to avoid stalling the Netty event loop.

Mono.fromCallable(() -> jdbcQuery())
    .subscribeOn(Schedulers.boundedElastic());

Reactive Redis cache example

@Service
public class UserService {
    private final ReactiveRedisTemplate<String, User> redisTemplate;
    public Mono<User> getUser(String id) {
        return redisTemplate.opsForValue()
                .get(id)
                .switchIfEmpty(loadFromDB(id));
    }
    private Mono<User> loadFromDB(String id) {
        return userRepository.findById(id)
                .flatMap(user -> redisTemplate.opsForValue()
                        .set(id, user)
                        .thenReturn(user));
    }
}

Server‑Sent Events (SSE) for real‑time push

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> stream() {
    return Flux.interval(Duration.ofSeconds(1))
            .map(i -> "event-" + i);
}

// Browser receives a continuous stream: event‑1, event‑2, …

API gateway usage (enterprise practice)

Typical stack: Spring Cloud Gateway + WebFlux. The non‑blocking architecture supports >100 000 concurrent connections, native SSE, WebSocket long‑lived connections and low latency.

Production incident post‑mortem

A migration kept a blocking JDBC call inside a Flux.range loop, blocking the Netty event loop. CPU reached 100 % and TPS dropped from 8 000 to 300.

Flux.range(1, 1_000_000)
    .map(i -> blockingQuery(i))
    .subscribe();

Fix: wrap the blocking call in Mono.fromCallable and schedule it on boundedElastic.

Flux.range(1, 1_000_000)
    .flatMap(i -> Mono.fromCallable(() -> blockingQuery(i))
        .subscribeOn(Schedulers.boundedElastic()))
    .subscribe();

// TPS recovered to ~9 500.

Benchmark results (real‑world comparison)

100 concurrent: MVC 5 k QPS vs WebFlux 5.2 k QPS.

1 000 concurrent: MVC 7 k vs WebFlux 13 k.

5 000 concurrent: MVC 6 k vs WebFlux 28 k.

10 000 concurrent: MVC crashes, WebFlux sustains 31 k.

Thread count: MVC uses 200‑500 threads; WebFlux needs only 16‑32.

Best‑practice checklist

Avoid blocking libraries (JDBC, JPA, RestTemplate); prefer R2DBC, WebClient, Reactive Redis.

Replace RestTemplate with WebClient for non‑blocking HTTP calls.

Control Flux concurrency with .flatMap(..., 100) or similar limits.

Apply rate‑limiting libraries such as Resilience4j or Sentinel.

Enable BlockHound to detect accidental blocking calls.

Future trends: Reactive + AI + Streaming

Combining WebFlux with Kafka, Flink and large‑language‑model token streams (e.g., ChatGPT, DeepSeek, Claude) creates a streaming architecture where AI tokens are emitted as a reactive flow.