Spring WebFlux & WebClient Expert

Specialized knowledge for reactive, non-blocking applications with Spring WebFlux and WebClient (Spring Boot 3.5, Framework 6.2.x, Reactor 2025.0).

Core Principles

Reactive Programming: Non-blocking, asynchronous with backpressure. WebClient uses Project Reactor (Mono/Flux).

• Mono<T>: 0 or 1 element (like Optional/CompletableFuture)
• Flux<T>: 0 to N elements (stream)

Critical Rules:

• Never .block() in reactive code (only tests)
• Always configure timeouts
• Reuse WebClient instances (connection pool)
• Return Mono/Flux from services
• Retry only transient errors (5xx, timeouts - NOT 4xx)

Quick Examples

Configuration (Spring Boot 3.5+)

@Bean
public WebClient webClient(WebClient.Builder builder) {
    return builder
        .baseUrl("https://api.example.com")
        .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
        .build();
}

// Properties
spring.webclient.connect-timeout=5s
spring.webclient.read-timeout=30s

Requests

// GET
Mono<User> user = webClient.get().uri("/users/{id}", id).retrieve().bodyToMono(User.class);

// POST
Mono<User> created = webClient.post().uri("/users").bodyValue(newUser).retrieve().bodyToMono(User.class);

Error Handling + Retry

.retrieve()
.onStatus(HttpStatus::is5xxServerError, res -> Mono.error(new ServerException()))
.bodyToMono(User.class)
.retryWhen(Retry.backoff(3, Duration.ofSeconds(1)).filter(this::isTransient))
.onErrorResume(ex -> Mono.just(User.GUEST_USER));

Operators

users.map(User::getName);                                    // sync transform
users.flatMap(u -> getOrders(u.getId()));                   // async transform
users.filter(User::isActive);                               // filter
Mono.zip(user, profile, orders).map(tuple -> new Dashboard(...)); // combine

Reference Files

When user needs detailed information, read the appropriate reference file:

references/webclient-basics.md

Read when user asks about:

• WebClient configuration and setup
• Timeouts (connect, read, write, response)
• Connection pooling optimization
• Headers, cookies, filters
• Properties configuration (Spring Boot 3.5)
• Multiple WebClient instances
• SSL/TLS setup
• Debugging with wiretap

Examples of when to read: "how to configure timeout", "connection pool tuning", "setup WebClient with SSL", "configure multiple clients"

references/webclient-requests.md

Read when user asks about:

• HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
• URI building with query parameters
• Request headers and cookies
• Form data and multipart uploads
• Streaming and SSE
• Concurrent requests with limits
• Response types (Mono, Flux, Entity, List)

Examples of when to read: "how to do POST request", "upload file", "query parameters", "concurrent requests", "streaming data"

references/error-handling.md

Read when user asks about:

• Error handling with onStatus
• Retry strategies (simple, backoff, conditional)
• Circuit breaker pattern
• Timeout handling
• Fallback mechanisms
• WebClient exception hierarchy
• Combining resilience patterns

Examples of when to read: "handle 4xx errors", "implement retry", "circuit breaker", "fallback strategy", "timeout recovery"

references/reactor-fundamentals.md

Read when user asks about:

• Mono vs Flux differences
• Creating publishers (just, empty, defer, etc)
• Operators: map, flatMap, filter, zip, merge, concat
• Schedulers and threading
• Backpressure with limitRate
• Context and subscription
• Collecting results (collectList, reduce)

Examples of when to read: "difference between map and flatMap", "how to combine Mono and Flux", "backpressure", "schedulers", "operators"

references/best-practices.md

Read when user asks about:

• Code review checklist
• Anti-patterns to avoid
• Performance optimization
• Testing strategies
• Security considerations
• Memory management
• When NOT to use WebFlux

Examples of when to read: "review my code", "best practices", "common mistakes", "optimization", "anti-patterns", "testing reactive code"

When to Read References

• Configuration issues → webclient-basics.md
• Making HTTP calls → webclient-requests.md
• Errors, retries, resilience → error-handling.md
• Reactive operators, Mono/Flux → reactor-fundamentals.md
• Code review, optimization → best-practices.md

Always provide concise answer from SKILL.md first. Read reference files only when user needs detailed explanation or you need specific implementation details.

Versions: Spring Boot 3.5.x | Framework 6.2.x | Reactor 2025.0