برنامه‌نویسی واکنشی: Reactor و WebFluxReactive Programming: Reactor & WebFlux

Let me put one fact on the table up front: classic Java assigned one thread to each web request and kept that thread parked until the very end — until the database answered or the downstream service replied. Simple and easy to reason about, but expensive. Reactive programming arrived to end that waste: instead of a thread sitting and waiting, you model the data as a pipeline of events that comes to you the moment it's ready. In this chapter you won't just memorize an operator list — you'll actually understand why the paradigm exists, where it wins, where it makes you suffer, and why Java 21's virtual threads rewrote the whole equation.

Part 0 — a few words you must feel before we start

Before any code, a few terms recur throughout this chapter. Let me plant them in your mind now.

• Blocking: a call that halts the thread until a result is ready. Like standing frozen at the checkout until the cashier swipes the card.
• Non-blocking: a call that returns immediately and says "I'll tell you when it's ready." The thread is freed to do other work.
• Synchronous / asynchronous: synchronous means you get the result right there, on the spot; asynchronous means the result arrives later, via a callback or event.
• Backpressure: a consumer's ability to say "slow down! I can only take 10 at a time." Without it, a fast producer can bury a slow consumer under data.
• Publisher / subscriber: the publisher is the source of data, the subscriber the destination. Their relationship is like a newspaper and its subscriber: until you subscribe, no paper arrives.

Mental model: why "a parked thread" is expensive

In the classic model (Servlet / Spring MVC), each request grabs a thread from a pool. When the code hits a database or HTTP call, that thread blocks: it enters WAITING and does no useful work until the response arrives. A platform thread costs roughly 1 MB of stack, so with, say, a pool of 200, your concurrency ceiling is effectively 200 in-flight requests — even if the CPU is idle. Your bottleneck isn't processing power; it's the number of blocked threads.

The non-blocking model runs on a small number of threads (typically one per CPU core). When it hits I/O, instead of waiting it registers a callback and frees the thread to serve the next request. The OS event-loop mechanism (like epoll on Linux) signals when data is ready. The result: 4 threads can juggle tens of thousands of concurrent connections — provided you never block anywhere in the chain (that "provided" becomes the biggest trap in this chapter).

Reactive Streams: the four-interface contract

Before Reactor, everyone did async their own way and libraries didn't compose. Reactive Streams is a tiny standard (just four interfaces) that even entered the JDK in Java 9 as java.util.concurrent.Flow. Reactor is one implementation of it.

The four core interfaces:

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

public interface Subscriber<T> {
    void onSubscribe(Subscription s); // connection established
    void onNext(T item);              // one item arrived
    void onError(Throwable t);        // error; failed termination
    void onComplete();                // successful termination
}

public interface Subscription {
    void request(long n);             // consumer wants n items ← backpressure
    void cancel();                    // I want no more
}

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

The golden point: the consumer controls demand via request(n). The producer may not emit more onNext than the total requested. That contract keeps the stream from flooding. A stream always terminates with exactly one onError or one onComplete — never both, and no signals are allowed afterward.

Mono and Flux: Reactor's two publishers

Reactor provides two Publisher implementations that everything is built on:

• Mono<T> — a stream that emits zero or one value then completes. Like "the user with this id" or "the result of one save." The reactive equivalent of Optional<T> or CompletableFuture<T>.
• Flux<T> — a stream that emits zero to many (unbounded) values. Like "all of today's orders" or an endless stream of events.

Mono<String> one   = Mono.just("Ada");
Mono<String> empty = Mono.empty();
Flux<Integer> many = Flux.just(1, 2, 3, 4);
Flux<Integer> range = Flux.range(1, 100);
Flux<Long>  ticks = Flux.interval(Duration.ofSeconds(1)); // infinite: 0,1,2,...

The most important rule: nothing runs until you subscribe

Flux<Integer> pipeline = Flux.range(1, 5)
        .map(i -> i * 2)
        .doOnNext(i -> System.out.println("passing: " + i));

// Nothing printed yet! Only the recipe was built.

pipeline.subscribe(i -> System.out.println("got: " + i)); // now it runs

This "laziness" is called being a cold publisher, which we return to shortly. In the WebFlux world you usually don't call subscribe yourself; the framework does it when it's ready to write the HTTP response. The big rule: never call .block() inside a reactive chain to "pull the value out" — that destroys the whole point (again, the chapter's central trap).

Operators: building the chain

Operators are what you chain onto a publisher to transform, filter, or combine data. Each operator returns a new publisher and leaves the previous one untouched (like the Stream API, but asynchronous).

map: one-to-one, synchronous transformation

map transforms each value into another using a synchronous function — exactly like Stream.map.

Flux.just("ada", "linus", "grace")
    .map(String::toUpperCase)      // "ADA", "LINUS", "GRACE"
    .map(String::length);          // 3, 5, 5

flatMap: a transformation that itself produces a publisher, asynchronously

Here is the most important distinction in the whole chapter. When the transforming function itself does something asynchronous (say, a database call that returns a Mono), using map gets you Flux<Mono<User>> — a publisher inside a publisher, useless. flatMap "flattens" these: it subscribes to each inner publisher and merges their outputs into a single Flux.

Flux<Long> orderIds = Flux.just(1L, 2L, 3L);

// wrong map: Flux<Mono<Order>> — a nested publisher
Flux<Mono<Order>> wrong = orderIds.map(id -> orderRepo.findById(id));

// right flatMap: Flux<Order> — flattened and concurrent
Flux<Order> right = orderIds.flatMap(id -> orderRepo.findById(id));

Crucial note: flatMap runs the inner publishers concurrently and with no ordering guarantee. If order matters, choose concatMap (sequential, order preserved, but slower) or flatMapSequential (runs concurrently but delivers ordered output).

filter, zip, and a few other everyday operators

Flux.range(1, 10)
    .filter(i -> i % 2 == 0)        // evens only: 2,4,6,8,10
    .take(3)                        // first 3 only: 2,4,6
    .defaultIfEmpty(-1);            // a default value if empty

// zip: pairs multiple publishers "in parallel" and combines
Mono<User>    user    = userRepo.findById(id);
Mono<Address> address = addressRepo.findByUser(id);
Mono<Profile> profile = Mono.zip(user, address,
        (u, a) -> new Profile(u.name(), a.city()));

zip shines when you have several independent calls and want all of them to run concurrently, then combine their results once all are ready — instead of awaiting them one after another. This is one place reactive truly excels: you wait for the maximum of the durations, not their sum.

Cold vs Hot: who decides when data flows

Most Reactor publishers are cold: Flux.range, Mono.fromCallable, a database call. Each new subscriber triggers a fresh execution.

Flux<Integer> cold = Flux.range(1, 3).map(i -> { System.out.println("computing " + i); return i; });
cold.subscribe(i -> System.out.println("A saw: " + i));
cold.subscribe(i -> System.out.println("B saw: " + i));
// "computing" runs fully twice — once for A, once for B

To create hot behavior or share one execution across subscribers, you use share()/publish() or Sinks:

// Sinks: the bridge between imperative code and the reactive world
Sinks.Many<String> sink = Sinks.many().multicast().onBackpressureBuffer();
Flux<String> hot = sink.asFlux();

hot.subscribe(s -> System.out.println("subscriber 1: " + s));
sink.tryEmitNext("event A");      // subscriber 1 sees it
hot.subscribe(s -> System.out.println("subscriber 2: " + s));
sink.tryEmitNext("event B");      // both see it; subscriber 2 missed "event A"

Schedulers and threading: which thread does data flow on?

A common misconception: "reactive means multi-threaded." No! By default, a reactive chain runs on the same thread that called subscribe — fully single-threaded. A Scheduler is the tool that lets you move parts of the chain onto other threads.

The main Scheduler types:

• Schedulers.parallel() — a fixed pool sized to the number of cores; for CPU-bound, short work.
• Schedulers.boundedElastic() — a capped pool that spins up temporary threads; specifically for wrapping blocking I/O work (e.g., a legacy JDBC driver) so it doesn't poison the rest of the flow.
• Schedulers.single() — a single shared thread; for work that must stay ordered on one thread.
• Schedulers.immediate() — the current thread; i.e., "don't switch at all."

publishOn versus subscribeOn

These two are the most frequent source of confusion. Let me state it firmly:

• subscribeOn(scheduler) determines which Scheduler the entire chain from the source upward — where subscription and data production begin — runs on. Its position in the chain doesn't matter; wherever you put it, it affects from the source.
• publishOn(scheduler) switches the thread from the point it's placed onward (downstream). Its position matters entirely; only the operators after it run on the new Scheduler.

Flux.range(1, 3)
    .map(i -> { log("map1 on: " + Thread.currentThread()); return i; })
    .publishOn(Schedulers.parallel())
    .map(i -> { log("map2 on: " + Thread.currentThread()); return i; })
    .subscribeOn(Schedulers.boundedElastic())
    .subscribe();
// map1 on boundedElastic (because of subscribeOn, from the source)
// map2 on parallel       (because of publishOn, from that point on)

Wrapping blocking work the right way

If you must call blocking code (say, a legacy SDK) in the reactive world, never call it directly; wrap it in Mono.fromCallable and push it onto boundedElastic so the event-loop thread stays free:

Mono<Report> report = Mono.fromCallable(() -> legacyBlockingClient.fetch(id)) // blocking
        .subscribeOn(Schedulers.boundedElastic());  // on a separate thread, not the event-loop

Error handling: in the reactive world, an error is also a signal

In imperative Java you catch errors with try/catch. But in a reactive chain, calls don't execute at that moment; so try/catch around building the chain is useless. An error travels as an onError signal within the stream and terminates the chain from that point. The error operators exist for exactly this:

userRepo.findById(id)
    // if it errors, provide a fallback value
    .onErrorReturn(User.GUEST)
    // or: depending on error type, switch to a different stream (fallback)
    .onErrorResume(TimeoutException.class, e -> cache.lookup(id))
    // or: translate the error type into a domain error
    .onErrorMap(SQLException.class, e -> new DataAccessException("db", e));

retry and backoff

For transient errors (a momentary network blip), you want to retry — but not immediately and not forever. retryWhen with Retry.backoff gives retries with an increasing delay (exponential backoff) and jitter:

httpClient.get("/inventory")
    .retryWhen(Retry.backoff(3, Duration.ofMillis(200))   // 3 attempts, starting at 200ms
        .jitter(0.5)                                       // random spread
        .filter(ex -> ex instanceof IOException)           // only retry these errors
        .onRetryExhaustedThrow((spec, sig) -> sig.failure())); // after exhaustion, original error

Backpressure in practice: when production outruns consumption

If a source produces fast and the consumer is slow (say, Flux.interval emitting every millisecond while the consumer lags), you must decide what to do with the overflow. Reactor gives explicit operators:

• onBackpressureBuffer() — hold the excess in a queue (risk: memory fills up if unbounded).
• onBackpressureDrop() — throw the excess away (for data where "freshness" beats "completeness," like GPS position).
• onBackpressureLatest() — keep only the latest value and drop the rest.

Flux.interval(Duration.ofMillis(1))         // a very fast producer
    .onBackpressureDrop(dropped -> log("dropped: " + dropped))
    .publishOn(Schedulers.boundedElastic())
    .subscribe(slowConsumer);

WebFlux versus Spring MVC

Spring has two entirely separate web stacks that must not be mixed in one application:

• Spring MVC — Servlet-based, thread-per-request model, blocking, usually on Tomcat. Simple, mature, and compatible with the whole JDBC/JPA ecosystem.
• Spring WebFlux — Reactive Streams-based, non-blocking, usually on Reactor Netty with an event loop. Controllers return Mono/Flux.

// WebFlux — a reactive controller
@RestController
class OrderController {
    private final OrderRepository repo; // ReactiveCrudRepository

    @GetMapping("/orders/{id}")
    Mono<Order> byId(@PathVariable Long id) {
        return repo.findById(id);           // no blocking; the framework subscribes
    }

    @GetMapping(value = "/orders/stream",
                produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    Flux<Order> stream() {
        return repo.findAll()               // a Server-Sent Events stream
                   .delayElements(Duration.ofSeconds(1));
    }
}

R2DBC: relational databases, but non-blocking

JDBC is inherently blocking: the ResultSet waits. So that the reactive stack can extend all the way down to the database, R2DBC (Reactive Relational Database Connectivity) was created — a fully non-blocking SPI for relational databases (Postgres, MySQL, SQL Server, ...).

public interface OrderRepository extends ReactiveCrudRepository<Order, Long> {
    Flux<Order> findByStatus(String status);          // Flux, not List
    Mono<Order> findByReference(String ref);          // Mono, not Optional
}

The biggest trap: blocking inside the reactive chain

This mistake is so common and so lethal that it deserves its own section. The entire reactive advantage comes from a small number of event-loop threads that never block. If even one blocking call (a Thread.sleep, a JDBC call, a legacy restTemplate, or a .block()) lands on an event-loop thread, that thread gets stuck — and since you have only a handful of them, the whole server's throughput collapses.

// Disaster: blocking on the event-loop thread
@GetMapping("/bad/{id}")
Mono<User> bad(@PathVariable Long id) {
    User u = jpaRepository.findById(id).get(); // blocking JDBC on the event-loop!
    return Mono.just(u);
}

Other common traps:

• Forgetting to subscribe. If nothing subscribes, nothing runs; you see no logs and get confused. (In WebFlux the framework subscribes, but in standalone service code it doesn't.)
• Losing context. ThreadLocal doesn't work in reactive because data hops across threads; to carry data (like security or trace info) you must use the Reactor Context (contextWrite/deferContextual).
• Useless stack traces. Errors often have cryptic stack traces; use Hooks.onOperatorDebug() or checkpoint() to trace the real path.
• Not testing with StepVerifier. Test reactive streams with StepVerifier, not ordinary asserts.

StepVerifier.create(Flux.just(1, 2, 3).map(i -> i * 2))
    .expectNext(2, 4, 6)
    .verifyComplete();

Virtual threads versus reactive: why the equation changed in 2026

Here is the most "current" discussion of the chapter. Reactive programming was built mainly to solve one problem: expensive platform threads blocking on I/O. But Java 21 finalized virtual threads (JEP 444), which solve the same problem with far simpler code.

With virtual threads, a blocking JDBC call no longer pins a platform thread; the JVM "unmounts" the virtual thread during I/O and the real carrier thread is freed. That means you can keep the familiar thread-per-request model, @Transactional, and the entire JPA ecosystem while simultaneously getting high throughput.

So when is reactive still genuinely worth it?

• Streaming and SSE/WebSocket at very high connection counts — Flux<ServerSentEvent> on Netty is far more efficient than SseEmitter on Tomcat.
• Real backpressure — when the consumer must signal capacity to the producer; virtual threads don't provide this inherently.
• An existing fully reactive stack — a team already on R2DBC, reactive MongoDB, and reactive Redis that wants to stay non-blocking end to end.
• Gateway/composition patterns — a service that composes dozens of downstream calls; Reactor's operators (zip, flatMap, timeout, retry) are very expressive here.

Virtual threads don't kill reactive's strengths, they just shrink its scope. Reactive shifted from "the default for high concurrency" to "the specialized tool for streaming, backpressure, and stream composition."

Best practices

• In WebFlux, never block anywhere in the chain; enable BlockHound in tests.
• For synchronous transforms use map; to go off to an asynchronous source use flatMap (and concatMap if order matters).
• Wrap unavoidable blocking work in Mono.fromCallable(...).subscribeOn(boundedElastic()).
• Don't use ThreadLocal to carry side data; use the Reactor Context.
• Test streams with StepVerifier, not ordinary asserts.
• Keep the reactive stack end to end: don't mix WebFlux with blocking JPA; use R2DBC or a reactive driver.
• For transient errors, retryWhen(Retry.backoff(...)) with jitter; for fallbacks, onErrorResume.
• Before choosing reactive, ask: "Is my problem really backpressure or streaming, or just high concurrency?" If the latter, virtual threads may be simpler and better.

Interview Questions

Flux<Integer> f = Flux.range(1, 3).doOnNext(i -> System.out.println("x" + i));
System.out.println("built");

List<Order> orders = repo.findAll().collectList().block();