Spring Cloud Gateway 도입하면서 겪은 라우팅 문제와 해결 체크리스트

Spring Cloud Gateway를 도입하면서 라우팅 설정 때문에 한참 삽질했던 경험이 있어요. 단순히 라우팅만 잘 설정하면 되겠지 하고 시작했는데, 예상보다 훨씬 까다로운 부분들이 있더라고요.

이 글에서는 제가 직접 겪었던 라우팅 문제와 그 해결 과정을 바탕으로, Spring Cloud Gateway를 쓸 때 반드시 확인해야 할 핵심 사항들을 ✅체크리스트 형태로 정리해봤어요. 특히 빠뜨리기 쉬운 부분에 더 신경 썼으니, 이 글만 끝까지 보면 라우팅 때문에 헤매는 일은 없을 거예요.

개발 환경 / 버전 정보

먼저 제가 사용한 환경부터 소개할게요. 개발하다가 버전 차이 때문에 헷갈릴 수도 있어서요.

• Java 17 - LTS 버전으로 안정적으로 개발 중입니다.
• Spring Boot 3.1.0 - Gateway 지원도 잘 되고 최신 문서 참고하기 좋았어요.
• Spring Cloud Gateway 2022.0.3 - 버전 호환성 필수 확인!
• 프로젝트는 Maven 기반으로 구성했습니다.

이렇게 하면 됩니다: 기본 라우팅 설정 방법

사실 기본 라우팅 설정은 공식 문서 예제만 따라가면 어렵지 않은데, 제 경험엔 여기서부터 꼼꼼하게 체크해야 할 부분들이 있었어요. 예를 들어 경로 매칭, 필터 적용 순서 같은 것들이죠.

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://USER-SERVICE
          predicates:
            - Path=/user/**
          filters:
            - StripPrefix=1
            - AddRequestHeader=X-Request-Source, gateway

위 예시는 간단한 사용자 서비스로 요청을 보내기 위한 설정입니다. 중요한 점은 StripPrefix=1가 들어가 있어서 요청 경로에서 /user 부분이 잘려나간다는 거예요. 만약 이 부분을 놓치면 뒤쪽 서비스가 요청을 이상하게 받을 수 있습니다.

여기서 많이 틀립니다: 라우팅 설정 체크리스트 ✅

많은 분들이 간과하는 중요한 체크리스트를 꼭 알려드려요. 저는 이걸 체크하면서 문제를 하나씩 해결했거든요.

• 경로 프리픽스 처리 여부 확인 - StripPrefix 또는 RewritePath 필터 적용 여부를 꼭 확인하세요.
• LB URI 사용 시 서비스 ID 정확성 - lb:// 뒤에 오는 서비스 이름이 정확해야 스프링 클라우드 내에서 제대로 인식돼요.
• Predicate 조건 우선순위 - 여러 라우트가 겹칠 때 어느 조건부터 매칭하는지도 꼭 따져야 합니다.
• 필터 순서 및 영향 범위 확인 - 특히 응답 헤더 또는 리퀘스트 수정 필터는 순서에 따라 동작이 크게 달라집니다.
• 실제 요청 URL과 라우터 매칭 테스트 - Postman이나 curl로 여러 케이스 직접 요청해보는 걸 권장합니다.

이 부분에서 막혔는데: 자주 보는 에러와 원인

한 가지 예로, 저는 LBURI가 잘못돼서 다음과 같은 에러가 났었어요.

org.springframework.cloud.gateway.support.NotFoundException: Unable to find instance for USER-SERVICE

이 에러는 서비스 이름이 잘못되었거나, Eureka(또는 다른 서비스 등록 서버)에 등록된 서비스가 없을 때 발생합니다. 이걸 모르면 라우팅 실패 원인을 찾는데 한참 걸려서 고생했어요.

다른 경우는 프리픽스 처리 문제로 백엔드 서비스에서 요청 경로가 이상하게 넘어가서 404 응답이 나오는 경우도 있었는데, 이때는 StripPrefix 필터를 제대로 사용했는지 다시 한번 점검하는 게 핵심이었어요.

심화: 커스텀 필터 추가하는 법

그런데 단순 라우팅만으로 부족할 때는 커스텀 필터도 만드는데요. 저는 인증 토큰 넣거나 로그를 남기려고 직접 필터를 작성했던 적 있어요.

import org.springframework.cloud.gateway.filter.GatewayFilter;
import org.springframework.cloud.gateway.filter.factory.GatewayFilterFactory;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

@Component
public class CustomHeaderFilter implements GatewayFilterFactory<CustomHeaderFilter.Config> {

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            exchange.getRequest().mutate()
                .header("X-Custom-Header", config.getValue())
                .build();
            return chain.filter(exchange).then(Mono.fromRunnable(() -> {
                // 응답 후 동작
            }));
        };
    }

    public static class Config {
        private String value;

        public String getValue() {
            return value;
        }

        public void setValue(String value) {
            this.value = value;
        }
    }
}

이 코드는 요청 헤더에 커스텀 값을 넣는 필터예요. 필터를 작성할 때는 GatewayFilterFactory를 상속해서 구성하고, apply() 메소드 안에서 로직을 구현하면 됩니다.

자주 물어보시는 것들

Q. 여러 라우트가 중복될 때 우선순위는 어떻게 되나요?

A. Spring Cloud Gateway는 application.yml에 선언된 라우트 순서대로 평가해서 첫 매칭된 라우트로 요청을 포워딩합니다. 그래서 더 구체적인 경로를 위쪽에 배치하는 게 좋아요.

Q. StripPrefix 대신 RewritePath를 써야 할 때는 언제인가요?

A. StripPrefix는 단순히 앞 경로 부분을 잘라내지만, RewritePath는 정규식으로 경로를 세밀하게 바꿀 수 있어요. 예를 들어 복잡한 경로 구조 변경이 필요할 때 RewritePath가 유용합니다.

Q. 설정이 맞는데도 라우팅이 안 되는 이유는 뭔가요?

A. 대개는 Eureka 같은 서비스 등록 서버와 연동 문제, 혹은 네트워크 방화벽 문제일 가능성이 큽니다. 또 실제 요청 경로와 설정한 Predicate 경로가 정확히 일치하는지 꼼꼼히 확인해 보세요.

Spring Cloud Gateway 라우팅이 잘 안 될 때는 사실 이 체크리스트만 쭉 따라보면 대부분 문제를 빨리 파악할 수 있었습니다. 저도 이 점을 몰라서 헤맸던 경험이 있으니까요.

마지막으로, 라우팅 설정 외에도 트래픽 관리, 장애 격리 같은 고급 기능들도 있는데요, 우선은 라우팅 기본을 완전히 이해하는 게 가장 중요해요. 그 다음에 필요에 따라 커스텀 필터나 리본, 서킷 브레이커 같은 기술을 더해 가면 좋고요.