| name | spring-cloud-gateway |
| description | Use when building Spring Cloud Gateway 5 on Spring Boot 4, including WebFlux or Web MVC routes, edge authentication, trusted headers, rate limits, timeouts, and resilience. Do not use for ordinary outbound HTTP clients or domain orchestration.
|
Spring Cloud Gateway 5
Keep the gateway an edge adapter. Do not move domain workflows into filters.
Compatibility and dependencies
- Use the latest Spring Cloud
2025.1.x release train for Spring Boot 4.
- Boot 4.1 support starts with Spring Cloud
2025.1.2.
- Import
spring-cloud-dependencies as a BOM and omit versions from individual Cloud dependencies.
- Choose exactly one gateway runtime.
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
</dependency>
Do not use the old spring-cloud-starter-gateway coordinate or force a Boot 3 release train onto
Boot 4. WebFlux requires Reactor Netty and cannot run as a traditional servlet WAR; Web MVC uses a
servlet runtime and WebMvc.fn.
Gateway 5 configuration namespaces
Gateway 5 separates server implementations in configuration:
- WebFlux:
spring.cloud.gateway.server.webflux.*
- Web MVC:
spring.cloud.gateway.server.webmvc.*
spring:
cloud:
gateway:
server:
webflux:
httpclient:
connect-timeout: 2000
response-timeout: 5s
routes:
- id: orders-api
uri: http://orders.internal
predicates:
- Path=/api/orders/**
filters:
- RemoveRequestHeader=X-User-Id
The Boot 3-era spring.cloud.gateway.routes and spring.cloud.gateway.httpclient paths do not bind
to Gateway 5's WebFlux server properties.
Route and security rules
- Use stable route IDs and explicit predicates.
- Remove client-provided forwarding, identity, and internal headers before creating trusted values.
- Keep path and host rewriting visible and covered by tests.
- Authenticate at the edge and authorize again in downstream services.
- Relay tokens only to services with the intended audience.
- Rate-limit by authenticated identity or a verified API key, not an untrusted address header.
- Set global connection and response timeouts with narrow route overrides.
- Retry only proven idempotent operations and only before response commitment.
- Keep fallbacks bounded and expose sustained upstream failure.
Testing and operations
- Test predicates, filters, trusted headers, CORS, timeouts, body limits, and status mapping.
- Use a controlled upstream server rather than mocking gateway internals.
- Record route ID, outcome, latency, and upstream failure with bounded metric tags.
- Test each selected runtime with its matching Spring Cloud Gateway test support.
Examples
examples/good-routes.yml shows Gateway 5 WebFlux configuration.examples/good-webmvc-routes.yml shows Gateway 5 Web MVC configuration.examples/bad-routes.yml preserves the stale configuration as a warning.
Official sources
Gotchas
- Agent uses
spring.cloud.gateway.routes on Gateway 5 - use the server-specific namespace.
- Agent uses
spring-cloud-starter-gateway on Boot 4 - select the WebFlux or Web MVC server starter.
- Agent selects a Cloud train without checking the exact Boot line - use the compatibility matrix.
- Agent trusts a public identity header - derive identity after authentication.
- Agent retries POST requests automatically - retry only proven idempotent operations.
- Agent puts business orchestration in filters - keep domain logic downstream.
- Agent omits response timeouts - stalled upstreams can exhaust resources.
