GW Spring Cloud Gateway 완전 가이드

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")}")
    }
}

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

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);
                });
        };
    }
}

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 {}
}

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

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", "주문 서비스가 일시적으로 불안정합니다. 잠시 후 다시 시도해 주세요.",
            "retryable", true,
            "timestamp", Instant.now().toString()
        );
    }
}

# API 성격별 권장값
# read API: fallback 가능, timeout 짧게, half-open 빠르게
# write API: fallback보다 명확한 실패 응답 선호, retry 중복 처리 주의

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

payments-write:
  failureRateThreshold: 30
  slowCallDurationThreshold: 2500ms
  waitDurationInOpenState: 30s

# 운영에서 반드시 같이 볼 지표
# - resilience4j_circuitbreaker_state
# - resilience4j_circuitbreaker_calls
# - gateway route별 5xx 비율
# - fallback 응답 비율
# - upstream service latency p95 / p99

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}"

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

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");
    }
}

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}"

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus,gateway
  endpoint:
    gateway:
      enabled: true
  metrics:
    tags:
      application: testforge-gateway