From f58f8a54dc981b0233d2ffdd7f742447d31f8c45 Mon Sep 17 00:00:00 2001 From: halo Date: Wed, 10 Jun 2026 03:54:46 +0900 Subject: [PATCH] docs: document that SimpleClientHttpRequestFactory is not suitable for WebMVC gateway Add a new http-client.adoc page for the WebMVC gateway documenting: - An IMPORTANT warning that SimpleClientHttpRequestFactory (URLConnection) cannot correctly forward 4xx/5xx responses and causes HTTP 500 errors - How to configure a suitable HTTP client factory via spring.http.clients.imperative.factory (jdk, okhttp, or apache) - Add the new page to nav.adoc The root cause: URLConnection throws IOException for error status codes, preventing the gateway from reading and forwarding the upstream error body. Any of JDK HttpClient, OkHttp, or Apache HttpComponents handle this correctly. Closes #3451 Co-Authored-By: Claude Sonnet 4.6 --- docs/modules/ROOT/nav.adoc | 1 + .../http-client.adoc | 62 +++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/http-client.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 58d9ea694..cdf76fa71 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -70,6 +70,7 @@ * xref:spring-cloud-gateway-server-webmvc.adoc[] ** xref:spring-cloud-gateway-server-webmvc/starter.adoc[] +** xref:spring-cloud-gateway-server-webmvc/http-client.adoc[] ** xref:spring-cloud-gateway-server-webmvc/glossary.adoc[] ** xref:spring-cloud-gateway-server-webmvc/how-it-works.adoc[] ** xref:spring-cloud-gateway-server-webmvc/java-routes-api.adoc[] diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/http-client.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/http-client.adoc new file mode 100644 index 000000000..b0e569d7e --- /dev/null +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/http-client.adoc @@ -0,0 +1,62 @@ +[[http-client]] += HTTP Client + +Spring Cloud Gateway Server MVC uses Spring Boot's `RestClient` infrastructure to forward requests to backend services. +The underlying `ClientHttpRequestFactory` is resolved from the application context, driven by `spring.http.clients.imperative.factory`. + +IMPORTANT: `SimpleClientHttpRequestFactory` (backed by `java.net.HttpURLConnection`) is **not suitable** for the WebMVC gateway. +`HttpURLConnection` throws a `java.io.IOException` (such as `FileNotFoundException` for 404 responses) instead of providing the response body for 4xx/5xx status codes. +The gateway cannot forward error responses correctly in this case, and the client will receive an `HTTP 500` instead of the actual upstream error status. + +== Selecting an HTTP Client + +Use one of the following supported implementations: + +=== JDK HttpClient (recommended, no extra dependency) + +Set the factory to `jdk` to use Java's built-in `HttpClient` (available since Java 11): + +.application.yml +[source,yaml] +---- +spring: + http: + clients: + imperative: + factory: jdk +---- + +=== OkHttp + +Add `com.squareup.okhttp3:okhttp` to your classpath. The factory is selected automatically when `okhttp3.OkHttpClient` is on the classpath, or you can set it explicitly: + +.application.yml +[source,yaml] +---- +spring: + http: + clients: + imperative: + factory: okhttp +---- + +=== Apache HttpComponents + +Add `org.apache.httpcomponents.client5:httpclient5` to your classpath, or set the factory explicitly: + +.application.yml +[source,yaml] +---- +spring: + http: + clients: + imperative: + factory: apache +---- + +NOTE: If you have OkHttp or Apache HttpComponents on the classpath, Spring Boot's auto-detection will prefer them over `SimpleClientHttpRequestFactory`, so the IMPORTANT notice above only applies when running without any of those libraries. + +== Related Documentation + +* xref:spring-cloud-gateway-server-webmvc/tls-and-ssl.adoc[TLS and SSL] – configure SSL bundles for backend calls +* https://docs.spring.io/spring-boot/reference/io/rest-client.html#io.rest-client.restclient[Spring Boot RestClient documentation]