Skip to main content
AIDevOps
  • Learn
  • Learning Paths
  • Practice
  • Open Source
  • Books
  • Engineering

    AI DevOpsThe full map of building and operating AI servicesLLMOpsLLM deployment · evaluation · observabilityHands-on ProjectsBuild AI Agent projects

    Knowledge

    DocsTechnical documentationBlogEngineering articlesPloggerDevelopment log feed

    Validate

    Certification3-level skills certification · coming soon
AI Models
LlamaTutorial|MistralTutorial|GemmaTutorial|DeepSeekTutorial|QwenTutorial
🌱 Spring Cloud
Spring Intro & RoadmapSpring Cloud GatewaySpring BootJava|Spring AISpring SecuritySpring BatchSpring JPA
🤖 AI Applied Development
Applied AI Intro & RoadmapHugging FaceLangChainLlamaIndexLLMOps|LangGraphMCPMulti-AgentAgent Evaluation
🧠 AI Core
AI Intro & RoadmapML FundamentalsLLM Fundamentals|Python AIC++|PyTorchTensorFlowJAX
🧠 AI Agent Development
Finance AI AgentLLM API ServerStock Investing AgentAIOps AI AgentEducation AI AgentCoding AI Agent
🐳 DevOps
DevOps Intro & RoadmapLinuxDockerCI/CD|Kubernetes BasicsK8s AdvancedPrometheusGrafana
🧱 Infrastructure
Infrastructure Intro & RoadmapNginxRedis
☁️ Cloud
Cloud Intro & RoadmapAWSGCPAzureNCPCloudflare
🎨 Frontend
Frontend Intro & RoadmapJavaScriptTypeScript|ReactNext.js|VueNuxt|Electron
📱 Mobile
Mobile Intro & RoadmapKotlinAndroidFlutter
⚙️ Backend
Backend Intro & RoadmapPython BasicsFastAPIDjangoFlask|CGoGinNode.js
💾 Database
DB Intro & RoadmapCore SQLOracleMySQLPostgreSQL|MongoDBVector DB
🧪 Testing
k6JMeternGrinder
AIDevOps

Engineering AI. From Code to Production.
An engineering learning platform for building and operating AI and AI Agents

Learn

  • All Guides
  • Learning Paths
  • AI Tutorial
  • Practice
  • Books

Resources

  • AI DevOps
  • LLMOps
  • Hands-on Projects
  • Docs
  • Blog
  • Plogger
  • Open Source
  • Certification (coming soon)

Start Here

  • AI Core Roadmap
  • AI Applied Development Roadmap
  • Spring Cloud Roadmap
  • DevOps Roadmap
  • Infrastructure Roadmap

 

  • Cloud Roadmap
  • Frontend Roadmap
  • Mobile Roadmap
  • Backend Roadmap
  • Database Roadmap
© 2026 AIDevOps. All rights reserved.
Terms of ServicePrivacy PolicySitemaptestforge.kr
  1. Home
  2. Learn
  3. Spring Cloud
  4. Spring Cloud Gateway
Spring Cloud API Gateway guide

GW Spring Cloud Gateway Complete Guide

Visitors

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.

Open the Web IDE →
API GatewayMSA routingAuth filterCircuit breakerRate limiting

Related frameworks & environments

🍃Spring Boot→☕Java→🔐Spring Security→🗄️Spring JPA→

Contents

0 / 16
  1. How to use this guide
  2. Architecture diagrams
  3. Gateway overview
  4. Project setup
  5. Route config
  6. Global filter
  7. Auth integration
  8. Circuit breaker
  9. CB tuning
  10. Rate limit
  11. Rate limit advanced
  12. Actuator metrics
  13. Spring Cloud Gateway design
  14. Operating standards
  15. Verification strategy
  16. Frequently asked questions
Contents 16 sections
  1. How to use this guide
  2. Architecture diagrams
  3. Gateway overview
  4. Project setup
  5. Route config
  6. Global filter
  7. Auth integration
  8. Circuit breaker
  9. CB tuning
  10. Rate limit
  11. Rate limit advanced
  12. Actuator metrics
  13. Spring Cloud Gateway design
  14. Operating standards
  15. Verification strategy
  16. Frequently asked questions

How to use this guide

How to read it

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.
AreaRole
RouteSelects the upstream service based on path, method, and host conditions
PredicateDecides which route a request matches
FilterCommon handling such as request/response headers, authentication, logging, and retries
ObservabilityObserve 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.
build.gradle.ktsKOTLIN
plugins {
    id("java")
    id("org.springframework.boot") version "3.3.5"
    id("io.spring.dependency-management") version "1.1.6"
}

java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } }

extra["springCloudVersion"] = "2023.0.3"

dependencies {
    implementation("org.springframework.cloud:spring-cloud-starter-gateway")
    implementation("org.springframework.cloud:spring-cloud-starter-circuitbreaker-reactor-resilience4j")
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    implementation("io.micrometer:micrometer-registry-prometheus")
}

dependencyManagement {
    imports {
        mavenBom("org.springframework.cloud:spring-cloud-dependencies:${property("springCloudVersion")}")
    }
}

Route config

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.
application.ymlYAML
server:
  port: 8080

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: http://user-service:8081
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=1
            - AddRequestHeader=X-Gateway, testforge

        - id: order-service
          uri: http://order-service:8082
          predicates:
            - Path=/api/orders/**
          filters:
            - StripPrefix=1

Global filter

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.
TraceIdFilter.javaJAVA
import java.util.UUID;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class TraceIdFilter {
    @Bean
    GlobalFilter addTraceId() {
        return (exchange, chain) -> {
            String traceId = UUID.randomUUID().toString();
            var request = exchange.getRequest().mutate()
                .header("X-Trace-Id", traceId)
                .build();

            return chain.filter(exchange.mutate().request(request).build())
                .doFinally(signal -> {
                    exchange.getResponse().getHeaders().add("X-Trace-Id", traceId);
                });
        };
    }
}

Auth integration

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;

@Component
public 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.
application.ymlYAML
spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: http://order-service:8082
          predicates:
            - Path=/api/orders/**
          filters:
            - StripPrefix=1
            - name: CircuitBreaker
              args:
                name: orderCircuitBreaker
                fallbackUri: forward:/fallback/orders

resilience4j:
  circuitbreaker:
    instances:
      orderCircuitBreaker:
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 20
        minimumNumberOfCalls: 10
        failureRateThreshold: 50
        slowCallRateThreshold: 50
        slowCallDurationThreshold: 2s
        waitDurationInOpenState: 20s
        permittedNumberOfCallsInHalfOpenState: 5
        automaticTransitionFromOpenToHalfOpenEnabled: true
  timelimiter:
    instances:
      orderCircuitBreaker:
        timeoutDuration: 3s
FallbackController.javaJAVA
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;

@RestController
public 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 retries

orders-read:
  failureRateThreshold: 50
  slowCallDurationThreshold: 1500ms
  waitDurationInOpenState: 15s

payments-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
StateMeaningGateway behavior
ClosedThe normal state. Requests are forwarded to the upstream service.Success/failure metrics keep being recorded.
OpenThe failure rate or slow call rate has crossed the threshold.Upstream calls are blocked and the fallback answers immediately.
Half-openAfter 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.
application.ymlYAML
spring:
  cloud:
    gateway:
      routes:
        - id: public-api
          uri: http://public-api:8083
          predicates:
            - Path=/api/public/**
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20
                key-resolver: "#{@ipKeyResolver}"

Circuit breaker tuning guide

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.
route-profile.ymlYAML
spring:
  cloud:
    gateway:
      routes:
        - id: catalog-read
          uri: http://catalog-service:8080
          predicates: [Path=/api/catalog/**]
          filters:
            - name: CircuitBreaker
              args:
                name: catalogReadCircuit
                fallbackUri: forward:/fallback/catalog

        - id: payment-write
          uri: http://payment-service:8080
          predicates: [Path=/api/payments/**]
          filters:
            - name: CircuitBreaker
              args:
                name: paymentWriteCircuit
                fallbackUri: forward:/fallback/payments

resilience4j:
  circuitbreaker:
    instances:
      catalogReadCircuit:
        slidingWindowSize: 50
        minimumNumberOfCalls: 20
        failureRateThreshold: 50
        slowCallRateThreshold: 60
        slowCallDurationThreshold: 1200ms
        waitDurationInOpenState: 15s
      paymentWriteCircuit:
        slidingWindowSize: 30
        minimumNumberOfCalls: 10
        failureRateThreshold: 30
        slowCallRateThreshold: 40
        slowCallDurationThreshold: 2500ms
        waitDurationInOpenState: 45s
Operations checklistTEXT
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
OptionWhat to tunePractical guideline
minimumNumberOfCallsThe minimum number of calls needed before statistics are computedUse 10-20 for low-traffic routes and 50 or more for busy routes to reduce accidental failure verdicts.
slidingWindowSizeThe sample size for computing the failure rateSmaller is more sensitive, larger is more stable. Start core APIs at 50-100 early in a rollout.
failureRateThresholdThe failure rate that switches to OpenStart conservatively: 50% for read APIs, 30-40% for sensitive APIs such as payment/authentication.
slowCallDurationThresholdThe duration above which a call counts as slowStart slightly above the upstream p95, and keep it shorter than the user timeout.
waitDurationInOpenStateHow long the Open state is heldConsider 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.
RateLimitKeyResolvers.javaJAVA
import org.springframework.cloud.gateway.filter.ratelimit.KeyResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import reactor.core.publisher.Mono;

@Configuration
public class RateLimitKeyResolvers {
    @Bean
    KeyResolver ipKeyResolver() {
        return exchange -> {
            String forwarded = exchange.getRequest().getHeaders().getFirst("X-Forwarded-For");
            String ip = forwarded != null
                ? forwarded.split(",")[0].trim()
                : exchange.getRequest().getRemoteAddress().getAddress().getHostAddress();
            return Mono.just("ip:" + ip);
        };
    }

    @Bean
    KeyResolver userKeyResolver() {
        return exchange -> Mono.justOrEmpty(exchange.getRequest().getHeaders().getFirst("X-User-Id"))
            .map(userId -> "user:" + userId)
            .defaultIfEmpty("anonymous");
    }

    @Bean
    KeyResolver apiKeyResolver() {
        return exchange -> Mono.justOrEmpty(exchange.getRequest().getHeaders().getFirst("X-Api-Key"))
            .map(apiKey -> "api-key:" + apiKey)
            .defaultIfEmpty("missing-api-key");
    }
}
tiered-rate-limit.ymlYAML
spring:
  cloud:
    gateway:
      routes:
        - id: search-free
          uri: http://search-service:8080
          predicates:
            - Path=/api/search/**
            - Header=X-Plan, free
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 5
                redis-rate-limiter.burstCapacity: 10
                key-resolver: "#{@userKeyResolver}"

        - id: search-pro
          uri: http://search-service:8080
          predicates:
            - Path=/api/search/**
            - Header=X-Plan, pro
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 50
                redis-rate-limiter.burstCapacity: 100
                key-resolver: "#{@userKeyResolver}"
Rate limit tuningTEXT
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 strategyBest forCaution
IP addressPublic APIs for anonymous users, crawler/bot defenseCan also limit legitimate users behind a NAT/proxy.
User IDFair usage control per signed-in userMust be applied after the authentication filter to be accurate.
API keyPartner/external integration APIsA leaked key does great damage, so a rotation policy is needed.
Tenant IDPer-organization limits in B2B SaaSIf 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.
application.ymlYAML
management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus,gateway
  endpoint:
    gateway:
      enabled: true
  metrics:
    tags:
      application: testforge-gateway

Spring Cloud Gateway practical design

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 pointQuestion to askPractical guideline
BoundariesWhich parts of the Spring Cloud Gateway code are most likely to change?Separate input/output, configuration, external integrations, and the core rules.
StateWhere is state created and where does it go away?Make the owner and lifecycle of state visible in the code.
FailureWhat 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.

Tip

  • filter order
  • route policy
  • fallback contract
  • circuit state alert

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 axisHow to verifyDefinition of done
CorrectnessAutomate the normal/failure cases.The core scenarios pass reproducibly.
Regression preventionWhen fixing a bug, leave the same case behind as a test.The same failure is not deployed again.
OperabilityCheck 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.

← Previous guideSpring Intro & RoadmapNext guide →Spring Boot