Spring Cloud Gateway로 API 게이트웨이 만들기 - 마이크로서비스 통합의 핵심 구성

마이크로서비스 환경에서는 수많은 서비스가 서로 통신하며 동작합니다. 하지만 외부에서 직접 각 서비스를 호출하게 되면 보안, 라우팅, 인증, 로깅 등의 관리가 복잡해집니다. 이 문제를 해결하기 위한 대표적인 솔루션이 바로 API 게이트웨이(API Gateway)입니다. 

 

API 게이트웨이란?

API 게이트웨이는 외부 클라이언트 요청을 내부 마이크로서비스로 라우팅하는 진입점 역할을 합니다. 즉, 모든 외부 요청은 Gateway를 통해 들어오며, Gateway는 요청 경로를 분석해 해당하는 서비스로 요청을 전달합니다.

Spring Cloud Gateway는 Netflix Zuul의 후속 버전으로, 비동기 논블로킹(reactive) 아키텍처 기반으로 설계되어 고성능 트래픽 처리가 가능합니다.

 

Spring Cloud Gateway의 주요 기능

• 라우팅 (Routing): 요청 경로에 따라 내부 서비스로 트래픽 전달
• 필터링 (Filtering): 요청 전·후 공통 로직 수행 (로깅, 인증, 헤더 추가 등)
• 로드 밸런싱: Eureka 또는 Spring Cloud LoadBalancer와 연동하여 서비스 인스턴스 분산 처리
• 보안 제어: JWT, OAuth2 기반 인증/인가 처리
• 모니터링: Spring Boot Actuator를 통한 트래픽 모니터링

 

Spring Cloud Gateway 기본 구조

Spring Cloud Gateway는 요청을 다음과 같은 순서로 처리합니다:

[클라이언트 요청] → [Route Predicate] → [Filter Chain] → [Target Service]

즉, 조건(Predicate)에 맞는 경로(Route)를 찾아 요청을 전달하고, 필터(Filter)를 통해 전후 처리를 수행합니다.

 

1. Gateway 프로젝트 생성

의존성 추가 (Gradle)

implementation 'org.springframework.cloud:spring-cloud-starter-gateway'
implementation 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-client'

Eureka와 연동하면 서비스명을 기반으로 자동 라우팅이 가능해집니다.

 

2. application.yml 설정

기본적인 게이트웨이 라우팅 설정은 아래와 같이 정의할 수 있습니다.

server:
  port: 8080

spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://USER-SERVICE
          predicates:
            - Path=/users/**
          filters:
            - AddRequestHeader=X-Gateway, SpringCloudGateway
            - AddResponseHeader=X-Response-Time, #{T(java.time.LocalDateTime).now()}
        - id: order-service
          uri: lb://ORDER-SERVICE
          predicates:
            - Path=/orders/**

lb:// 접두사는 Eureka를 통해 등록된 서비스명으로 트래픽을 분산시킨다는 의미입니다. 즉, 직접 IP를 지정하지 않고도 서비스 간 라우팅이 가능합니다.

 

3. Predicate (라우팅 조건)

Predicate는 요청이 어떤 Route로 전달될지 판단하는 조건식입니다. 다음은 자주 사용되는 Predicate 종류입니다:

• Path: 요청 경로 기준 (예: /users/**)
• Method: HTTP 메서드 기준 (GET, POST 등)
• Header: 특정 헤더 포함 여부 기준
• Query: 쿼리 파라미터 기준
• After / Before / Between: 시간대 기준

- id: report-service
  uri: http://localhost:8083
  predicates:
    - Path=/reports/**
    - Method=GET
    - Header=X-Auth-Token, .+

위 예시는 /reports/** 요청 중 GET 메서드이며 X-Auth-Token 헤더가 존재하는 경우에만 라우팅됩니다.

 

4. Filter (공통 로직 처리)

Gateway의 강력한 기능 중 하나는 Filter를 통한 요청 전후 제어입니다. Filter는 요청(Request)과 응답(Response)에 공통 로직을 주입할 수 있습니다.

커스텀 필터 예제

@Component
public class LoggingFilter implements GlobalFilter, Ordered {

    private static final Logger log = LoggerFactory.getLogger(LoggingFilter.class);

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        log.info("Request Path: {}", request.getPath());
        return chain.filter(exchange)
                .then(Mono.fromRunnable(() -> {
                    ServerHttpResponse response = exchange.getResponse();
                    log.info("Response Status: {}", response.getStatusCode());
                }));
    }

    @Override
    public int getOrder() {
        return -1; // 필터 실행 우선순위
    }
}

위 예제는 모든 요청의 경로와 응답 상태를 로그로 남기는 글로벌 필터입니다. 실무에서는 여기에 JWT 검증, 요청 시간 측정, 공통 응답 처리 등을 추가해 활용합니다.

 

5. CORS 설정 (Cross-Origin Resource Sharing)

게이트웨이는 여러 도메인에서 요청을 받을 수 있으므로, CORS 설정을 반드시 해주어야 합니다.

spring:
  cloud:
    gateway:
      globalcors:
        corsConfigurations:
          '[/**]':
            allowedOrigins: "https://example.com"
            allowedMethods:
              - GET
              - POST
              - PUT
              - DELETE
            allowedHeaders: "*"
            allowCredentials: true

이 설정을 통해 특정 도메인에서의 API 호출을 허용할 수 있습니다.

 

6. Actuator로 라우트 모니터링

Spring Boot Actuator를 이용하면 Gateway의 라우팅 상태를 실시간으로 확인할 수 있습니다.

implementation 'org.springframework.boot:spring-boot-starter-actuator'

서버 실행 후 아래 주소로 접근하면 현재 등록된 라우트를 확인할 수 있습니다.

GET http://localhost:8080/actuator/gateway/routes

이를 통해 라우팅 정보, 필터 적용 여부 등을 손쉽게 모니터링할 수 있습니다.

 

실무 적용 시 팁

• JWT 인증 필터: 공통 인증 로직을 Gateway에서 처리하여 서비스 간 인증 중복 제거
• Rate Limiting: 사용자별 요청 제한 설정 (RedisRateLimiter 활용)
• 로그 트레이싱: Sleuth + Zipkin을 연동해 요청 흐름 추적
• 캐시 처리: 자주 호출되는 정적 API는 Gateway 레벨에서 캐싱
• 모듈화: 인증, 모니터링, 필터 등을 별도 패키지로 분리하여 유지보수성 향상

 

주의할 점

• 모든 요청이 Gateway를 통하기 때문에 성능 병목 가능성 존재 → 스레드 풀, 연결 타임아웃 설정 필요
• 필터 체인 과도 구성 시 응답 지연 발생
• SSL 종단(termination) 처리 위치를 명확히 (Gateway vs Load Balancer)
• Config Server나 Eureka 장애 시 라우팅 불가 → 이중화 구성 필수

 

---

 

Spring Cloud Gateway는 마이크로서비스 환경의 핵심 진입점으로, 보안·인증·라우팅·필터링을 일관되게 관리할 수 있습니다. 단일 API 관문을 통해 서비스의 확장성과 안정성을 모두 확보할 수 있으며, 실무에서는 Gateway를 중심으로 Config Server, Eureka, Security 등을 연동하여 완전한 MSA 구조를 구성합니다.