You are migrating a blocking Spring MVC service from RestTemplate to WebClient. What are the key pitfalls and how do you avoid them?

## Framing the migration RestTemplate is in maintenance mode, so new work should use WebClient. But a naive port that replaces every `restTemplate.getForObject` with `webClient...retrieve().bodyToMono(...).block()` keeps the app **fully blocking** — you get the modern API and resilience operators, not scalability. Be explicit about the goal. ## Pitfall 1 — Thread model / .block() - In a **Spring MVC (servlet)** app, controller methods run on servlet threads; calling `.block()` there is *safe* but still holds that thread for the call's duration (same cost as RestTemplate). - **Never call `.block()` on a Reactor Netty event-loop thread** (e.g. inside another reactive pipeline running on the loop) — Reactor actively detects some of these and throws, and it can deadlock the loop. - True benefit comes from returning `Mono`/`Flux` up the stack (WebFlux) or offloading, not from blocking. ## Pitfall 2 — Client lifecycle / connection pool - Build **one** `WebClient` (or share a `WebClient.Builder` bean) and reuse it. Reactor Netty keeps a connection pool per client; building per request creates/destroys pools and kills performance. ## Pitfall 3 — Timeouts (the silent production killer) RestTemplate set connect/read timeouts on its `ClientHttpRequestFactory`. With WebClient you configure the underlying `HttpClient`: ```java HttpClient httpClient = HttpClient.create() .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2000) // connect .responseTimeout(Duration.ofSeconds(5)); // response WebClient client = WebClient.builder() .clientConnector(new ReactorClientHttpConnector(httpClient)) .baseUrl(baseUrl) .build(); ``` Also add an operator-level `.timeout(Duration)` as a backstop. Without explicit timeouts, a stalled upstream can exhaust the pool. ## Pitfall 4 — Error handling translation - RestTemplate threw `HttpClientErrorException` (4xx) / `HttpServerErrorException` (5xx) / `RestClientException`. - WebClient throws **`WebClientResponseException`** (with per-status subtypes). Update `try/catch` and use `retrieve().onStatus(...)` to map statuses to domain exceptions. Reactive recovery uses `onErrorResume`/`onErrorMap`, not try/catch. ## Pitfall 5 — Buffer / codec limits - Default in-memory buffer is **256 KB**; larger bodies throw `DataBufferLimitException`. Raise it: `builder.codecs(c -> c.defaultCodecs().maxInMemorySize(2 * 1024 * 1024))`. ## Pitfall 6 — API surface mapping - `getForObject` → `get().uri().retrieve().bodyToMono(T).block()`. - `postForEntity` → `post().uri().bodyValue(body).retrieve().toEntity(T).block()`. - `exchange(...)` (RestTemplate) → `retrieve()` or `exchangeToMono` depending on whether you need status/headers. - Note: RestTemplate's `exchange` is unrelated to WebClient's deprecated `exchange()`. ## Pitfall 7 — Observability & context propagation - Blocking `RestTemplate` interceptors and `ThreadLocal`-based context (MDC, security context) don't automatically propagate across reactive threads. In reactive chains use Reactor **Context** / Micrometer context-propagation. In a purely-blocking `.block()` port this is less of an issue but worth verifying for logging/tracing. ## Rollout strategy 1. Introduce a shared `WebClient` bean with explicit timeouts, pool sizing, and buffer limits. 2. Port one endpoint, keep `.block()` at the controller boundary, verify behavior and error mapping. 3. Load-test to size the connection pool and confirm timeouts. 4. Migrate hot paths to fully reactive only if the service (and downstream) can benefit end-to-end.