Route

🚪 Spring Cloud Gateway Route

— 요청의 생명주기를 지배하는 ‘워크플로우 정의서’ 🧭

스프링 클라우드 게이트웨이(SCG)에서 Route(라우트)는 단순한 URL 매핑 규칙이 아닙니다.
👉 요청이 언제 들어오고, 어떤 조건에서 선택되며, 어떤 가공을 거쳐, 어디로 흘러가는지를 정의하는
하나의 “요청 처리 워크플로우 명세서”라고 이해하셔야 합니다.

이번 글에서는 Route가 어떻게 설계되고, 내부에서 어떤 메커니즘으로 동작하는지 깊이 있게 분석해 보겠습니다. 🔍

🧩 1. Route란 무엇인가? — 논리적 구조부터 이해하기

Route는 다음 질문에 대한 완전한 답변 세트입니다.

❓ 이 요청은
• 어디로(URI)
• 어떤 조건일 때(Predicate)
• 무엇을 가공해서(Filter)
보내야 하는가?

이를 구성하는 핵심 요소를 하나씩 살펴보겠습니다.

🆔 ① Route ID — 관측 가능성을 위한 최소 단위

Route의 ID는 단순한 이름이 아닙니다.

id: user-service

✨ 왜 중요한가?

• 📊 로그 분석 (어떤 라우트가 요청을 처리했는지)
• 📈 메트릭 수집 (라우트별 TPS, 실패율)
• 🔧 운영/유지보수 (문제 발생 시 빠른 식별)

➡️ UUID 자동 생성도 가능하지만,
반드시 의미 있는 이름을 명시적으로 부여하는 것이 실무의 정석입니다.

🔍 ② Predicate — “이 요청, 내가 처리해도 될까?” 🤔

Predicate는 Boolean 판별식입니다.
모든 요청은 먼저 Predicate의 심문을 통과해야 합니다.

⚙️ 기술적 기반

• Java 8 Predicate<T> 인터페이스
• HTTP 요청의 모든 요소를 조건으로 사용 가능

📌 주요 Predicate Factory

Predicate	의미
Path	URL 경로 매칭
Method	HTTP Method(GET, POST…)
Header	헤더 값 검사
Host	도메인 기반 라우팅
Query	쿼리 파라미터
Cookie	쿠키 값
RemoteAddr	클라이언트 IP
Before / After / Between	⏰ 시간 기반 제어

🔗 다중 조건 결합 규칙

predicates:
  - Path=/api/users/**
  - Method=GET

➡️ 모든 조건은 AND 조건으로 결합됩니다.
즉, 하나라도 실패하면 라우트는 선택되지 않습니다 ❌

🧪 ③ Filter — 요청과 응답을 조각하는 실험실 🧬

Filter는 Route의 핵심 두뇌입니다.
실질적인 비즈니스 관문 로직이 여기서 수행됩니다.

🔀 Filter의 두 가지 레벨

1️⃣ GatewayFilter

• 특정 Route에만 적용
• 예: 특정 서비스 전용 헤더 변환

2️⃣ GlobalFilter

• 모든 Route에 공통 적용

• 예:

  • 🔐 인증/인가
  • 📜 로깅
  • 📊 메트릭 수집

🛠️ Filter에서 가능한 일들

• 헤더 추가 / 제거
• Request / Response Body 변환
• Rate Limiting 🚦
• Circuit Breaker 연동 ⚡
• Retry / Fallback 처리

➡️ MSA에서 ‘횡단 관심사(Cross-Cutting Concern)’를 처리하는 최전선입니다.

🎯 ④ URI — 요청의 최종 목적지

Route의 마지막 종착역입니다.

🧱 정적 라우팅

uri: http://localhost:8081

⚖️ 동적 라우팅 (권장)

uri: lb://USER-SERVICE

• lb:// 스키마 사용
• Load Balancer + Service Discovery(Eureka 등) 연동
• 인스턴스 증가/감소에 자동 대응 🧠

⚙️ 2. Route 내부 동작 메커니즘 (Deep Dive) 🧠

라우팅의 출발점은 내부 컴포넌트인
👉 RoutePredicateHandlerMapping 입니다.

🔄 처리 흐름 한눈에 보기

1️⃣ 매칭 단계

• 모든 Route의 Predicate를 순차 평가
• 최초로 통과한 후보들을 수집

2️⃣ 우선순위 결정 (order)

• 여러 Route가 매칭되면
  👉 order 값이 낮을수록 우선

3️⃣ 필터 체인 구성

• GlobalFilter + GatewayFilter
• 하나의 Reactive Filter Chain 생성

4️⃣ 논블로킹 실행

• Netty + Project Reactor 기반
• ❌ Thread Blocking 없음
• ⚡ 고성능 이벤트 루프 처리

➡️ 이 모든 과정이 비동기 / 논블로킹으로 처리됩니다.

🧠 3. 전문가를 위한 고급 Route 활용 전략

🔄 다이내믹 라우팅 (Runtime Route 변경)

서버 재시작 없이 라우트 변경이 가능합니다.

• RouteDefinitionWriter 사용
• 메모리 즉시 반영
• Redis, DB 등 외부 저장소와 연계 가능

➡️ 멀티 테넌트, A/B 테스트, 트래픽 전환에 매우 유용합니다 🔥

🏷️ Route Metadata — 라우트에 의미를 부여하다

metadata:
  role: ADMIN

💡 활용 예

• 권한 체크
• 트래픽 그룹 구분
• 커스텀 정책 적용

exchange.getAttribute(GATEWAY_ROUTE_ATTR);

➡️ Route를 단순 경로가 아닌 ‘정책 단위’로 승격시킵니다.

✅ 4. 실무 모범 사례 (Best Practices)

🥇 1. 우선순위 설계는 필수

• /** 같은 광범위 패턴은 항상 마지막 order

🥈 2. 공통 로직은 GlobalFilter로

• 인증, 로깅, 모니터링은 중앙집중화 🎯

🥉 3. 에러 처리 전략 수립

• DefaultErrorWebExceptionHandler 커스터마이징
• 사용자 친화적 에러 응답 제공 💬

✍️ 마무리하며

Spring Cloud Gateway의 Route는
❌ “URL 분기 규칙”이 아니라
✅ MSA 요청 흐름을 설계하는 선언적 워크플로우 엔진입니다.