Spring Boot 시리즈 33편 – Spring Cloud Gateway: API 게이트웨이 설계와 트래픽 라우팅 전략

B컷개발자 2025. 5. 20. 12:46

728x90

Spring Cloud Gateway를 활용한 API Gateway 설계와 트래픽 라우팅 전략을 정리합니다. 마이크로서비스 구조에서 게이트웨이의 역할, 필터 구성, 라우팅, 인증 및 보안 적용까지 실무 기준으로 설명합니다.

마이크로서비스 구조에서 사용자 요청이 각 서비스를 직접 호출하도록 설계하면
서비스의 수가 늘어날수록 복잡도와 보안 리스크가 증가합니다.
이 문제를 해결하는 핵심 요소가 바로 API Gateway입니다.

Spring Cloud Gateway는 Netflix Zuul의 뒤를 이어,
Spring 생태계에서 가장 널리 사용되는 비동기 논블로킹 기반의 API Gateway 프레임워크입니다.

1. Spring Cloud Gateway란?

항목 설명

목적	사용자 요청을 여러 내부 서비스로 라우팅하고, 공통 정책을 게이트웨이에서 처리
아키텍처 기반	Netty 기반 WebFlux (비동기 Reactive)
특징	라우팅, 필터링, 인증, 로깅, Load Balancing까지 통합 처리 가능
실무 활용	마이크로서비스 트래픽 관리, 모놀리식 분리, 인증 통합, 블루그린 배포 등

2. 의존성 및 설정

1) Gradle 의존성 추가

implementation 'org.springframework.cloud:spring-cloud-starter-gateway'

Spring Cloud BOM 적용 필요

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:2023.0.0"
    }
}

2) application.yml 예시

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

이 설정은 /api/users/** 경로로 들어온 요청을 http://localhost:8081로 프록시합니다.

3. 라우팅 구성 요소

구성요소 설명

routes	게이트웨이가 프록시할 대상 경로 정의
predicates	요청 조건 필터 (예: 경로, 시간, 메소드 등)
filters	요청/응답 변경 또는 기능 추가 (예: 인증, 헤더 추가, 로깅 등)
uri	실제로 트래픽을 전달할 대상 서비스 주소

4. 주요 Predicate 및 Filter 사용 예시

Path 기반

- Path=/api/products/**

Method 기반

- Method=GET

Header 기반

- Header=X-User-Role, admin

필터 예시: 응답 헤더 추가

filters:
  - AddResponseHeader=X-Processed-By, Gateway

필터 예시: 요청 로그 출력

@Component
public class LoggingFilter implements GlobalFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        log.info("Request: {}", exchange.getRequest().getURI());
        return chain.filter(exchange);
    }
}

5. 인증/보안 처리 전략

API Gateway는 인증과 인가를 통합하는 위치로도 이상적입니다.

1) JWT 인증 처리 필터 예시

@Component
public class JwtAuthFilter implements GlobalFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = extractToken(exchange.getRequest());
        if (!isValid(token)) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }
        return chain.filter(exchange);
    }
}

이런 구조를 통해 각 서비스는 인증 로직 없이도 JWT 기반 보호를 받을 수 있습니다.

6. 로드밸런싱 및 마이크로서비스 연동

Spring Cloud Gateway는 Spring Cloud LoadBalancer, Eureka 등과 통합되어
uri: lb://서비스명 형태로 내부 서비스 호출이 가능합니다.

uri: lb://order-service

→ Eureka를 통해 order-service의 인스턴스를 찾아 트래픽을 분산시킴

7. 장애 대응 및 Circuit Breaker 적용

Spring Cloud Gateway는 Resilience4j 기반의 Circuit Breaker도 연동 가능합니다.

filters:
  - name: CircuitBreaker
    args:
      name: fallbackCmd
      fallbackUri: forward:/fallback

마무리 요약

항목 요약

게이트웨이 역할	트래픽 라우팅, 공통 인증, 보안, 로깅, 필터 처리
핵심 구성	routes, predicates, filters, uri
인증 통합	GlobalFilter 기반 JWT 처리 구조
마이크로서비스 연동	Eureka + LoadBalancer 연동 가능
장애 대응	Circuit Breaker, fallback URI 처리 가능

다음 편 예고

Spring Boot 시리즈 34편: Eureka와 서비스 디스커버리 구조 – 마이크로서비스 환경에서의 자동 인스턴스 탐색 전략

728x90