Spring Cloud Gateway 도입하며 겪은 라우팅 문제와 해결 경험

저도 처음엔 Spring Cloud Gateway라는 용어부터 생소했어요. 사실, API 게이트웨이라는 개념도 뭐가 뭔지 감이 잘 안 왔거든요. 그런데 회사 프로젝트에 이걸 도입하면서 라우팅 관련해서 여러 문제가 생기고, 직접 부딪혀서 해결하는 과정에서 알게 된 내용을 정리해 봤습니다.

이 글에서는 초보자 입장에서 Spring Cloud Gateway가 뭔지, 왜 쓰는지부터 시작해서, 제가 개발하면서 겪었던 라우팅 이슈들, 그리고 그 해결법을 사례 위주로 풀어갈게요. 코드 예시도 한 점씩 넣어서 이해하는 데 도움되도록 최대한 쉽게 썼습니다.

Spring Cloud Gateway와 API 게이트웨이, 이게 뭔데요?

사실 이 부분이 처음 접하는 분들한테 가장 헷갈리는 개념인 것 같아요. 간단히 말하면, API 게이트웨이는 여러 마이크로서비스를 통합해서 외부 요청을 한 곳에서 받아서 적절한 서비스로 보내주는 '중간 출입구' 역할을 합니다.

그중 Spring Cloud Gateway는 스프링 생태계에서 제공하는 API 게이트웨이 솔루션인데요, 라우팅, 필터링, 부하 분산 등 다양한 기능을 지원해 줍니다. 그래서 복잡한 시스템에서 요청 흐름을 관리하는 데 편리하죠.

저도 처음엔 "라우팅이 뭐고 필터링은 또 뭐야?" 했는데, 간단히 설명하자면, 라우팅은 요청 URL을 보고 어느 서비스로 보낼지 결정하는 과정입니다. 필터링은 이 요청이나 응답을 가로채서 추가 작업(로그 찍기, 인증 등)을 하는 거예요.

Spring Cloud Gateway 도입하면서 겪은 라우팅 이슈 관련 정보

사용한 개발 환경과 버전

제가 작업한 환경은 다음과 같아요.

• Java 17
• Spring Boot 3.1.3
• Spring Cloud Gateway 4.0.6

Gradle을 쓰는 분은 build.gradle에 다음 의존성을 넣어주시면 됩니다.

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

처음 라우팅 설정 해봤는데, 이렇게 하면 됩니다

제가 처음 했던 라우팅 설정입니다. application.yml에 간단하게 원하는 경로와 대상 URI를 적으면 돼요.

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: http://localhost:8081
          predicates:
            - Path=/user/**

이렇게 하면, /user/**로 오는 모든 요청이 http://localhost:8081로 포워딩됩니다.

Spring Cloud Gateway 도입하면서 겪은 라우팅 이슈 관련 정보

여기서 많이 틀리는 경로 매칭과 라우팅 문제

그런데 여기서 문제가 발생했는데, 바로 경로 매칭 방식 때문이었어요. 저도 한참 동안 요청이 이상하게 가서 왜 그런지 몰랐죠.

Spring Cloud Gateway는 기본적으로 입력된 경로에 맞게 Path 프레디케이트를 사용해 요청을 라우팅하는데, 이 경로 매칭을 할 때 와일드카드(*) 위치나 슬래시(/) 처리에 민감합니다. 잘못 설정하면 요청이 전혀 다른 곳으로 가거나 404가 뜨기도 해요.

예를 들어 /user/**라고 했는데 실제 요청 경로가 /user인 경우, 이 패턴이 요청을 매칭하지 못해서 문제가 생기는 거죠.

해결 방법 : 경로 패턴 신경 쓰기

저는 이런 식으로 바꿔서 해결했어요.

predicates:
  - Path=/user/**
  - Path=/user

요청 경로가 /user 또는 /user/로 끝날 때도 정확히 매칭하도록 추가했더니 훨씬 안정적으로 동작하더라고요.

실제로 겪은 라우팅 에러와 원인 분석

가장 골치 아팠던 문제 중 하나는 404 에러였어요. API 게이트웨이를 거쳐서 호출하면 정상인데, Spring Cloud Gateway를 통하면 404가 나오더라고요.

이게 왜 그랬냐면, 라우팅 경로가 요청의 URI 일부를 잘라내지 않아서, 대상 서비스가 올바른 엔드포인트를 못 찾았던 겁니다.

// 문제의 라우팅 설정 예시
spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: http://localhost:8082
          predicates:
            - Path=/order/**

위 설정은 /order/** 경로를 localhost:8082로 보내는데, 요청이 /order/list였을 때 대상 서비스 쪽에서는 /order/list 전체 경로를 받아버려서 해당 경로가 없는 거예요.

이 문제는 필터 설정으로 해결

Spring Cloud Gateway의 StripPrefix 필터를 쓰면, URI의 앞부분을 잘라낼 수 있어요. 이렇게 하면 대상 서비스가 예상하는 경로가 넘어가서 문제를 해결할 수 있습니다.

spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: http://localhost:8082
          predicates:
            - Path=/order/**
          filters:
            - StripPrefix=1

여기서 StripPrefix=1은 URI의 첫 번째 경로 조각(/order)를 잘라내겠다는 뜻입니다. 그래서 /order/list가 대상 서비스에선 /list로 전달되죠.

Spring Cloud Gateway 도입하면서 겪은 라우팅 이슈 관련 정보

추가로 알게 된 라우팅 팁들

사실 Spring Cloud Gateway는 다양한 필터와 프레디케이트 옵션이 있어서 한 번에 익히기 어려울 수 있어요. 그래서 제가 직접 써보면서 좋은 팁 몇 가지를 공유할게요.

• PrefixPath 필터: StripPrefix와는 반대로, 앞에 경로를 추가하고 싶을 때 씁니다.
• Retry 필터: 대상 서비스가 가끔 실패할 때 재시도 로직을 자동으로 넣어 줍니다.
• Custom 필터 작성: Java 코드로 직접 필터를 만들어서 요청 로그를 찍거나, 인증 토큰을 검사하는 등 원하는 기능을 만들 수 있습니다.

제가 직접 만들어 본 간단한 Custom 필터 코드도 보여드릴게요.

import org.springframework.cloud.gateway.filter.GatewayFilter;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.core.Ordered;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;

@Component
public class CustomLogFilter implements GatewayFilter, Ordered {

    @Override
    public Mono filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        System.out.println("[CustomLogFilter] Request URI: " + exchange.getRequest().getURI());
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -1; // 필터 순서 지정
    }
}

이 필터를 등록하고 라우팅 설정에 붙이면 모든 요청 URI 로그를 찍을 수 있어서 문제 파악에 도움이 많이 됐어요.

자주 물어보시는 라우팅 관련 질문

Q. 프록시 헤더 설정 같은 건 따로 해야 하나요?

A. 보통 기본 설정으로도 잘 동작하지만, 인증이나 CORS 문제 발생 시 spring.cloud.gateway.forwarded.enabled 설정으로 헤더 처리를 조절할 수 있어요.

Q. 로드 밸런싱은 어떻게 하나요?

A. Spring Cloud Gateway는 spring-cloud-starter-loadbalancer 의존성을 추가하면 여러 서비스 인스턴스에 균등 분산도 가능해요. URI를 lb://service-name 형태로 설정하면 됩니다.

마무리하자면, 저도 처음엔 Spring Cloud Gateway 라우팅 하나만 해도 헤매고 삽질 엄청 했는데, 직접 부딪혀서 설정을 조금씩 바꾸면서 문제를 해결해 나가니까 점점 익숙해졌어요. 라우팅 경로 패턴과 필터 기능을 제대로 써야 안정적으로 서비스가 돌아가는 게 핵심이라는 걸 몸소 느꼈습니다.

마지막으로, 게이트웨이 관련해서 인증 처리, 모니터링, 부하 분산 같은 심화 주제도 있으니, 이 부분도 차근차근 경험해 보면 분명 도움이 될 거예요.

📌 함께 보면 좋은 글

• JPA Auditing으로 생성·수정 시간 자동화하면서 겪은 비용 비교 경험