Spring Reactive

Build non-blocking, reactive web applications with Spring WebFlux and Project Reactor. This skill focuses on production patterns, especially MDC context propagation which is the #1 pain point in reactive applications.

When to Use Me

•Implement reactive REST endpoints with WebFlux
•Propagate MDC context (traceId, requestId) across async boundaries
•Configure WebClient with proper timeouts, retries, and error handling
•Debug "context loss" issues where traceId disappears in logs
•Chain reactive operators (Mono/Flux) correctly
•Detect and handle blocking calls in reactive code
•Test reactive streams with StepVerifier

What I Do

•Guide MDC context propagation setup with ContextRegistry and Hooks
•Provide WebClient configuration patterns (connection pools, timeouts)
•Explain Mono/Flux operator selection and chaining
•Help debug context loss and blocking call issues
•Show StepVerifier testing patterns
•Cover error handling strategies in reactive streams

MDC Context Propagation

This is critical. Without proper setup, MDC context (traceId, spanId, requestId) is lost when crossing reactive boundaries.

Required Configuration (Spring Boot 3.x / Reactor 3.5+)

java

@Configuration
public class ReactorContextConfig {
    @PostConstruct
    public void setupContextPropagation() {
        // Enable automatic context propagation (Reactor 3.5+)
        Hooks.enableAutomaticContextPropagation();

        // Register MDC accessor with null-safe handling
        ContextRegistry.getInstance().registerThreadLocalAccessor(
            "mdc",
            () -> Optional.ofNullable(MDC.getCopyOfContextMap()).orElse(Map.of()),
            map -> { if (map != null) MDC.setContextMap(map); },
            MDC::clear
        );
    }
}

Key Points

•Use Micrometer context-propagation integration for production (recommended over DIY)
•Context flows per-subscription within the same reactive chain
•Use deferContextual to read Reactor Context; don't assume operators "drop" context
•WebFilter captures context: .contextWrite(ctx -> ctx.put("mdc", contextMap))

Reactor Patterns

Mono/Flux Selection

Use Case	Type	Why
Single value or empty	`Mono<T>`	0..1 elements
Collection/stream	`Flux<T>`	0..N elements
Void operation	`Mono<Void>`	Side effects only
Optional result	`Mono<T>` with `switchIfEmpty`	Handle empty case

Common Operators

java

// Transform
mono.map(x -> transform(x))           // Sync
mono.flatMap(x -> asyncCall(x))       // Async

// Handle empty
mono.switchIfEmpty(Mono.defer(() -> fallback()))
mono.defaultIfEmpty(defaultValue)

// Error handling
mono.onErrorResume(ex -> fallbackMono())
mono.onErrorMap(ex -> new CustomException(ex))

// Combine
Mono.zip(mono1, mono2, (a, b) -> combine(a, b))
Flux.merge(flux1, flux2)  // Interleaved
Flux.concat(flux1, flux2) // Sequential

Anti-Patterns

java

// BAD: Blocking in reactive chain
mono.map(x -> blockingCall(x))  // Blocks event loop!

// GOOD: Offload to bounded scheduler
mono.flatMap(x -> Mono.fromCallable(() -> blockingCall(x))
    .subscribeOn(Schedulers.boundedElastic()))

WebClient Configuration

Configure HttpClient with timeouts, add MDC propagation filter via Mono.deferContextual(), handle errors with .onStatus(), retry with Retry.backoff().

Blocking Detection

Violation	Solution
`Thread.sleep()`	`Mono.delay(Duration)`
JDBC calls	Use R2DBC or `subscribeOn(Schedulers.boundedElastic())`
`InputStream.read()`	Use `DataBufferUtils`
Synchronized blocks	Use `Mono.fromCallable().subscribeOn()`

Enable BlockHound in dev/test to detect blocking violations automatically.

Common Errors

Error	Cause	Solution
MDC values null in logs	Context not propagated	Enable `Hooks.enableAutomaticContextPropagation()`
`block()/blockFirst()` error	Blocking on event loop	Use `subscribeOn(Schedulers.boundedElastic())`
Timeout on blocking read	WebClient timeout	Configure timeouts in HttpClient
Context is empty	New Mono without context	Use `Mono.deferContextual()` or `contextWrite()`

Testing with StepVerifier

java

@Test
void shouldProcessReactively() {
    StepVerifier.create(service.process("input"))
        .expectNext("expected")
        .verifyComplete();
}

@Test
void shouldPropagateContext() {
    Mono<String> result = service.getTraceId()
        .contextWrite(ctx -> ctx.put("mdc", Map.of("traceId", "test-123")));

    StepVerifier.create(result)
        .expectNext("test-123")
        .verifyComplete();
}

WebTestClient Testing

java

@WebFluxTest(OrderController.class)
class OrderControllerTest {
    @Autowired
    private WebTestClient webClient;

    @MockBean
    private OrderService orderService;

    @Test
    void shouldReturnOrder() {
        when(orderService.findById(1L)).thenReturn(Mono.just(order));

        webClient.get().uri("/orders/1")
            .exchange()
            .expectStatus().isOk()
            .expectBody(Order.class).isEqualTo(order);
    }
}

Backpressure Basics

Strategy	Use When
`onBackpressureBuffer()`	Slow consumer, bounded buffer OK
`onBackpressureDrop()`	Latest value matters, can drop old
`limitRate(n)`	Control request batch size

Context7 Integration

For up-to-date Spring WebFlux documentation:

code

libraryName: "Spring WebFlux" or "Project Reactor"
Queries: "WebClient configuration", "Mono Flux operators", "Context propagation"

Reference Navigation

Topic	Reference	Load When
Full MDC WebFilter	research.md	Complete implementation
WebClient advanced config	research.md	Connection pool tuning, DNS resolver
Operator deep dive	research.md	Complete operator catalog
BlockHound setup	research.md	Blocking detection configuration

Related Skills

Skill	Use For
spring-boot-core	General Spring Boot patterns
spring-testing	Testing strategies including WebTestClient
opentelemetry-tracing	Distributed tracing setup

spring-reactive

Spring Reactive

When to Use Me

What I Do

MDC Context Propagation

Required Configuration (Spring Boot 3.x / Reactor 3.5+)

Key Points

Reactor Patterns

Mono/Flux Selection

Common Operators

Anti-Patterns

WebClient Configuration

Blocking Detection

Common Errors

Testing with StepVerifier

WebTestClient Testing

Backpressure Basics

Context7 Integration

Reference Navigation

Related Skills

Resources