How to build the entry point of an MSA with Spring Cloud Gateway: the API Gateway, routing, filters, authentication integration, circuit breakers, rate limiting, and observability.
Advanced
Updated Oct 1, 2026
~9 min read
13 sections
14 code examples
Web IDE lab included
GW
Spring Cloud Gateway Web IDE
Run code in the browser with nothing to install and learn through step-by-step examples.
Understanding Spring Cloud Gateway as a real-world workflow
How to build the entry point of an MSA with Spring Cloud Gateway: the API Gateway, routing, filters, authentication integration, circuit breakers, rate limiting, and observability. Rather than listing concepts, this guide is organized so you can follow the content in the order you have to make decisions on a real project.
Key perspective
Backend / systems development
Before syntax, pin down the boundaries a request crosses: validation, processing, storage, and response.
API GatewayMSA routingAuth filterCircuit breakerRate limiting
Architecture diagrams
To make what you read stick, it helps to capture the flow as a picture first. The two diagrams below are reference maps you can keep coming back to while learning Spring Cloud Gateway.
Learning flow
Rendering diagram…
Architecture view
Rendering diagram…
Spring Cloud Gateway overview
When you first open Spring Cloud Gateway, the big picture matters more than individual commands. This section starts with the problems the concepts ahead were created to solve.
Spring Cloud Gateway is a WebFlux-based API Gateway. It routes client requests to internal services and gathers cross-cutting concerns such as authentication, logging, header transformation, and traffic control in the Gateway layer.
Area
Role
Route
Selects the upstream service based on path, method, and host conditions
Predicate
Decides which route a request matches
Filter
Common handling such as request/response headers, authentication, logging, and retries
Observability
Observe the Gateway state with Actuator, Micrometer, and Prometheus
Project setup
Here you look at Project setup alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Start with Spring Boot 3.x, Spring Cloud Gateway, and Actuator as the base combination. The Gateway runs on the reactive stack (WebFlux), so adding spring-boot-starter-web alongside causes a conflict, and versions must be managed with the Spring Cloud BOM so the Gateway, Boot, and Circuit Breaker versions do not drift apart.
Here you look at Route config alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Define path-based routing first. The Gateway is the boundary that separates the public external URLs from the internal service URLs, so clients need to know only the Gateway address and never have to care how many services there really are or where they run. Stripping the outward-facing path prefix with StripPrefix lets each internal service keep its own URL scheme unchanged.
Here you look at Global filter alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Attaching a trace id to every request makes it easy to connect logs across services. A GlobalFilter applies not to a specific route but to every request passing through the Gateway, so cross-cutting concerns you do not want to rewrite for each route, such as authentication, logging, and header injection, can be gathered here in one place.
Here you look at Auth integration alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A structure in which the Gateway first checks whether a JWT is present and each service verifies the detailed permissions once more is the stable choice in practice. If the Gateway fully verifies the token signature and expiry as well, authentication logic tends to end up scattered across two places (the Gateway and the services), so split the roles: the Gateway focuses on being a first line of defense that quickly filters on "is there a token?", and each service is responsible for judging the actual user identity and permissions.
AuthGatewayFilter.javaJAVA
import org.springframework.cloud.gateway.filter.GatewayFilter;import org.springframework.cloud.gateway.filter.factory.AbstractGatewayFilterFactory;import org.springframework.http.HttpStatus;import org.springframework.stereotype.Component;@Componentpublic class AuthGatewayFilter extends AbstractGatewayFilterFactory<AuthGatewayFilter.Config> { public AuthGatewayFilter() { super(Config.class); } @Override public GatewayFilter apply(Config config) { return (exchange, chain) -> { String auth = exchange.getRequest().getHeaders().getFirst("Authorization"); if (auth == null || !auth.startsWith("Bearer ")) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } return chain.filter(exchange); }; } public static class Config {}}
Circuit breaker
Here you look at Circuit breaker alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A circuit breaker is a protective device that stops a downstream service failure from spreading into a failure of the whole Gateway. When timeouts, 5xx responses, and connection errors for a particular service cross a threshold, it opens the circuit and, for a set time, returns a fallback response or sends traffic down an alternative path. In a Gateway it is especially useful in front of user-facing APIs for blocking failure propagation, failing fast, and providing a fallback UX.
import java.time.Instant;import java.util.Map;import org.springframework.http.HttpStatus;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.ResponseStatus;import org.springframework.web.bind.annotation.RestController;@RestControllerpublic class FallbackController { @GetMapping("/fallback/orders") @ResponseStatus(HttpStatus.SERVICE_UNAVAILABLE) public Map<String, Object> orderFallback() { return Map.of( "status", 503, "code", "ORDER_SERVICE_UNAVAILABLE", "message", "The order service is temporarily unstable. Please try again shortly.", "retryable", true, "timestamp", Instant.now().toString() ); }}
Example production guidelinesYAML
# Recommended values by API type# read API: fallback possible, short timeout, quick half-open# write API: prefer a clear failure response over a fallback; beware duplicate processing from retriesorders-read: failureRateThreshold: 50 slowCallDurationThreshold: 1500ms waitDurationInOpenState: 15spayments-write: failureRateThreshold: 30 slowCallDurationThreshold: 2500ms waitDurationInOpenState: 30s# Metrics you must watch alongside it in production# - resilience4j_circuitbreaker_state# - resilience4j_circuitbreaker_calls# - 5xx ratio per gateway route# - fallback response ratio# - upstream service latency p95 / p99
State
Meaning
Gateway behavior
Closed
The normal state. Requests are forwarded to the upstream service.
Success/failure metrics keep being recorded.
Open
The failure rate or slow call rate has crossed the threshold.
Upstream calls are blocked and the fallback answers immediately.
Half-open
After the wait time passes, only some requests are let through as a test.
Goes back to Closed on success and to Open again on failure.
Rate limit
Here you look at Rate limit alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Applying a Redis-based rate limit lets you control excessive requests per user/service. Even when the number of Gateway instances grows, the counters are shared in Redis, so unlike counting separately per instance, an accurate limit is kept against the total traffic, and with the key-resolver you are free to choose the basis you want, such as IP or user ID.
Here you look at Circuit breaker tuning guide alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Circuit breaker values should differ according to the nature of the service. Read APIs protect the user experience with short timeouts and fallbacks, while for write APIs such as payment/order creation, duplicate processing and data consistency matter more, so aggressive retries and arbitrary fallbacks should be avoided.
What to check before turning on a circuit breaker
1. Does the fallback response fit the client UX?
2. Could retries on POST/PUT requests cause duplicate creation/duplicate payment?
3. Is timeoutDuration shorter than the client timeout?
4. Does an alert fire when the fallback ratio surges?
5. When the Open state persists, can you tell an upstream failure apart from a Gateway misconfiguration?
Recommended alerts
- circuit state stays OPEN for more than 1 minute
- fallback response ratio above 5% on a 5-minute average
- consecutive half-open probe failures
- p95 latency of a particular route approaching slowCallDurationThreshold
Option
What to tune
Practical guideline
minimumNumberOfCalls
The minimum number of calls needed before statistics are computed
Use 10-20 for low-traffic routes and 50 or more for busy routes to reduce accidental failure verdicts.
slidingWindowSize
The sample size for computing the failure rate
Smaller is more sensitive, larger is more stable. Start core APIs at 50-100 early in a rollout.
failureRateThreshold
The failure rate that switches to Open
Start conservatively: 50% for read APIs, 30-40% for sensitive APIs such as payment/authentication.
slowCallDurationThreshold
The duration above which a call counts as slow
Start slightly above the upstream p95, and keep it shorter than the user timeout.
waitDurationInOpenState
How long the Open state is held
Consider 10-20 seconds for services with short outages and 30-60 seconds for external integrations that recover slowly.
Rate limit advanced
Here you look at Rate limit advanced alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A rate limit is not simply a feature that reduces traffic; it is a Gateway policy for fairness, cost protection, and failure isolation. Limiting by IP is a good baseline defense for public APIs, while for signed-in users and partner APIs it is more accurate to limit by user id, tenant id, or API key.
replenishRate
- The number of tokens refilled per second.
- Match it to the average RPS you want to allow steadily.
burstCapacity
- The maximum number of tokens allowed in a burst.
- Too low, and short bursts from normal users also get a 429.
- Too high, and the protection weakens during an incident.
requestedTokens
- The number of tokens one request consumes.
- Costly APIs can be priced higher, at 5-10 tokens for example.
Operating guidelines for 429 responses
- Send a Retry-After header so the client knows when to retry.
- For login/payment/write APIs, design it together with the client policy to prevent endless retries.
- The 429 ratio is a sign of user inconvenience, so do not treat it purely as a measure of successful blocking.
Key strategy
Best for
Caution
IP address
Public APIs for anonymous users, crawler/bot defense
Can also limit legitimate users behind a NAT/proxy.
User ID
Fair usage control per signed-in user
Must be applied after the authentication filter to be accurate.
API key
Partner/external integration APIs
A leaked key does great damage, so a rotation policy is needed.
Tenant ID
Per-organization limits in B2B SaaS
If an organization has many users, use it together with a user limit.
Actuator metrics
Here you look at Actuator metrics alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
The Gateway sits where it easily becomes a bottleneck, so latency, status codes, and request volume per route must be observed.
Spring Cloud Gateway practical design is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
With Spring Cloud Gateway, traffic policy design matters more than route definitions. Authentication, rate limits, circuit breakers, fallbacks, and observability should differ per route.
Decision point
Question to ask
Practical guideline
Boundaries
Which parts of the Spring Cloud Gateway code are most likely to change?
Separate input/output, configuration, external integrations, and the core rules.
State
Where is state created and where does it go away?
Make the owner and lifecycle of state visible in the code.
Failure
What does the caller receive on failure?
Decide the timeout, fallback, and error contract first.
Spring Cloud Gateway operating standards
This section covers Spring Cloud Gateway operating standards from a practical perspective. Instead of memorizing the concept, focus on the situations in which you would reach for it.
The Gateway is where failures concentrate, so always watch the latency, 4xx/5xx, 429, fallback ratio, and circuit state per route.
Spring Cloud Gateway verification strategy
Spring Cloud Gateway verification strategy is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
Verify route predicates, filter order, fallback responses, and the rate limit key resolver with integration tests.
Quality axis
How to verify
Definition of done
Correctness
Automate the normal/failure cases.
The core scenarios pass reproducibly.
Regression prevention
When fixing a bug, leave the same case behind as a test.
The same failure is not deployed again.
Operability
Check the logs, metrics, and alerts.
There is a path for tracing the cause when a problem occurs.
Spring Cloud Gateway: frequently asked questions
Why do I need an API gateway?
It is the single entry point that receives requests in front of several services and routes each to the right one. Features every service needs, such as authentication, rate limiting, logging, and CORS, are handled in one place, and external addresses stay the same when the internal service layout changes.
How do Spring Cloud Gateway and Nginx differ?
Nginx is a general-purpose reverse proxy driven by configuration files, and Spring Cloud Gateway is an application where filters and routing rules are written in Java. When you need processing tied to business logic, such as per-user permission checks, and the team knows Spring, Spring Cloud Gateway is convenient. For static files and simple proxying, Nginx is lighter.
Why should I not use blocking code in a filter?
Spring Cloud Gateway is non-blocking and serves many requests with a small number of threads. Running code that holds a thread inside a filter, such as a synchronous database call, stalls the other requests that thread was handling. External calls must be written with a reactive client.