Spring Cloud Gateway에서 Java DSL로 라우팅 설정

 

 

 

Spring Cloud Gateway는 Spring 생태계에서 널리 쓰이는 API Gateway 솔루션이다.
간단한 설정으로 라우팅, 필터링, 보안, 모니터링 기능을 제공하며, Spring WebFlux 기반으로 비동기/논블로킹 처리를 지원한다.

application.yml이 아닌 Java DSL 방식으로 라우트를 등록하는 방법과 이를 담는 GatewayConfig 클래스를 예시로 살펴본다.

 

 

1. GatewayConfig 클래스

Spring Cloud Gateway에서 라우팅 정보를 등록하는 방법은 크게 두 가지이다.

1. application.yml 설정 기반
2. Java DSL 기반 (RouteLocator Bean 등록)

여기서 Java DSL 기반의 라우팅 설정은 @Configuration 클래스 안에서 RouteLocator 타입의 @Bean 메서드를 선언하여 구현한다. 이 메서드 안에서 각 라우트를 정의하고, 필요에 따라 필터를 적용한다.

 

 

2. 기본 예시 코드

아래는 Java DSL 방식으로 라우트를 등록하는 간단한 예시

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 routes(RouteLocatorBuilder builder) {
        return builder.routes()
                .route("example-route", r -> r.path("/api/**")
                        .filters(f -> f.addRequestHeader("X-Gateway", "SpringCloudGateway"))
                        .uri("http://localhost:8080"))
                .build();
    }
}

위 예시는 다음과 같은 라우트를 하나 등록한다.

• ID: "example-route"
• 조건: 요청 경로가 /api/** 인 경우
• 필터: 요청 헤더에 X-Gateway: SpringCloudGateway 추가
• 목적지: http://localhost:8080 으로 전달

클라이언트가 /api/... 로 요청을 보내면, 게이트웨이가 요청 헤더를 하나 추가한 후 localhost:8080 서버로 프록시하는 라우트가 생성된다.

 

 

3. DSL 체인 구조

DSL 체인은 다음과 같은 단계로 흘러간다.

1. routes.route("id", r -> { ... })
   → 라우트 ID와 조건, 필터, 목적지를 정의한다.
2. r.path("/api/**")
   → 경로 기반 프레디케이트(조건)를 설정한다.
3. .filters(...)
   → 라우트에 적용할 필터를 정의한다. 예: 헤더 추가, 경로 재작성, 인증 필터 적용 등
4. .uri("http://...")
   → 실제 요청을 전달할 목적지 주소를 지정한다.

마지막에 .build()를 호출하면 모든 라우트가 담긴 RouteLocator 인스턴스가 반환된다.

 

 

4. 여러 라우트를 등록하는 방법

한 개 이상의 라우트를 등록할 때는 builder.routes() 체인 안에 .route()를 여러 번 이어서 작성하면 된다.

@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
            .route("user-service", r -> r.path("/user/**")
                    .uri("http://localhost:8081"))
            .route("order-service", r -> r.path("/order/**")
                    .filters(f -> f.addRequestHeader("X-Service", "Order"))
                    .uri("http://localhost:8082"))
            .build();
}

• /user/** 요청은 localhost:8081 로 전달된다.
• /order/** 요청은 요청 헤더를 하나 추가한 뒤 localhost:8082 로 전달된다.

 

5. 커스텀 필터 적용하기

Gateway는 기본 제공 필터 외에도 직접 필터를 만들어 적용할 수 있다.
예를 들어, JWT 토큰을 검증하는 커스텀 필터를 만든 뒤 특정 라우트에만 적용할 수 있다.

@Bean
public RouteLocator routes(RouteLocatorBuilder builder, JwtAuthFilter jwtAuthFilter) {
    return builder.routes()
            .route("secure-route", r -> r.path("/secure/**")
                    .filters(f -> f.filter(jwtAuthFilter.apply(new JwtAuthFilter.Config())))
                    .uri("http://localhost:8083"))
            .build();
}

위 예시는 /secure/** 경로로 들어오는 요청에 대해 JWT 인증 필터를 거친 뒤 목적지로 전달한다.

 

 

---

 

• Spring Cloud Gateway는 API Gateway를 쉽게 구현할 수 있는 솔루션이다.
• Java DSL을 사용하면 GatewayConfig 클래스에서 라우트와 필터를 코드로 선언할 수 있다.
• 라우트는 ID, 조건(Path Predicate), 필터, 목적지 URI 네 가지 요소로 구성된다.
• DSL 체인의 흐름은 route → path → filters → uri → build 순서이다.
• 커스텀 필터를 작성하여 보안, 로깅, 모니터링 등을 라우트에 적용할 수 있다.