Spring Cloud Gateway로 API 게이트웨이 구축과 라우팅

소개

마이크로서비스 환경에서 API 게이트웨이는 외부 요청을 중앙에서 관리하고 라우팅, 인증, 로깅, 트래픽 제어 같은 공통 기능을 담당한다. Spring Cloud Gateway는 Spring Boot와 자연스럽게 통합되며, 선언적 라우팅과 필터를 통해 유연한 게이트웨이 구성이 가능하다. 본문에서는 spring cloud gateway 예제와 gateway routing spring boot, spring boot api gateway 설정을 중심으로 실용적인 예제를 제공한다.

왜 Spring Cloud Gateway를 선택하는가

Spring Cloud Gateway는 Spring WebFlux 기반으로 비동기 처리와 높은 확장성을 제공한다. 또한 RouteLocatorBuilder나 YAML 기반 선언식으로 라우팅을 정의할 수 있어 운영과 유지보수가 쉬운 편이다. 기본 제공되는 필터와 Predicates로 인증, 헤더 조작, 리다이렉션 등이 간결하게 구현된다.

사전 준비와 의존성

Spring Boot 프로젝트에서 Spring Cloud Gateway를 사용하려면 의존성을 추가해야 한다. Maven을 사용하는 경우 pom.xml에 spring-cloud-starter-gateway 추가가 필요하다.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>gateway-sample</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-gateway</artifactId>
    </dependency>
  </dependencies>
</project>

기본 라우팅 설정 (application.yml)

간단한 라우트는 application.yml에 선언식으로 정의할 수 있다. 이 방식은 구성 관리와 빠른 수정에 유리하다.

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

Java Route DSL 예제

코드 기반 라우팅이 필요한 경우 RouteLocatorBuilder를 사용하면 동적 라우트나 복잡한 조건을 손쉽게 구현할 수 있다. 다음 예제는 경로 매칭과 헤더 추가를 포함한다.

import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class GatewayConfig {
  @Bean
  public RouteLocator customRoute(RouteLocatorBuilder builder) {
    return builder.routes()
      .route("user_route", r -> r.path("/users/**")
        .filters(f -> f.addRequestHeader("X-From-Gateway", "true"))
        .uri("http://localhost:8081"))
      .route("order_route", r -> r.path("/orders/**")
        .filters(f -> f.stripPrefix(1))
        .uri("http://localhost:8082"))
      .build();
  }
}

간단한 커스텀 필터

필요에 따라 GlobalFilter를 구현해 공통 작업을 처리할 수 있다. 예를 들어 요청 로깅이나 응답 시간 측정에 활용된다.

import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class LoggingFilter implements GlobalFilter, Ordered {
  @Override
  public int getOrder() { return 0; }

  @Override
  public Mono<Void> filter(org.springframework.web.server.ServerWebExchange exchange,
                               org.springframework.cloud.gateway.filter.GatewayFilterChain chain) {
    long start = System.currentTimeMillis();
    return chain.filter(exchange).then(Mono.fromRunnable(() -> {
      long elapsed = System.currentTimeMillis() - start;
      System.out.println("Request to " + exchange.getRequest().getURI() + " took " + elapsed + "ms");
    }));
  }
}

테스트 방법

로컬에서 각 마이크로서비스를 포트별로 띄운 뒤 curl로 게이트웨이를 호출하면 라우팅 동작을 확인할 수 있다.

curl -i http://localhost:8080/users/1
curl -i http://localhost:8080/orders/123

운영을 위한 고려사항

• 보안: 인증과 권한 부여는 게이트웨이에서 중앙 관리가 가능하다. JWT 검증이나 OAuth2 연동을 검토한다.
• 관측성: 요청/응답 로깅, 트레이싱, 메트릭을 연동해 문제 원인 파악을 용이하게 한다.
• 회복력: 재시도, 서킷브레이커, 제한 시간 설정으로 다운스트림 서비스 영향을 완화한다.
• 스케일링: WebFlux 기반이므로 논블로킹 처리가 가능하며, 필요 시 인스턴스 수를 조정한다.
• 로드밸런싱: URI 대신 로드밸런서 (예: lb://service-name) 사용으로 서비스 디스커버리와 통합 가능하다.

마무리

Spring Cloud Gateway는 Spring Boot와 깊이 통합되어 라우팅과 필터링을 간결하게 구현한다. 예제에서 본 application.yml 기반 설정과 RouteLocatorBuilder 기반 코드는 서로 보완적으로 사용 가능하다. 처음 접하는 환경에서도 spring cloud gateway 예제와 gateway routing spring boot, spring boot api gateway 설정을 참고하면 기본 구조를 빠르게 이해하고 확장할 수 있다.