Predicate

🚦 Spring Cloud Gateway Predicate

— 요청을 Route로 보낼지 말지 결정하는 핵심 로직의 모든 것

MSA 환경에서 Spring Cloud Gateway(SCG) 는 단순한 라우터가 아닙니다.
SCG는 “이 요청을 어디로, 언제, 어떤 조건에서 보낼 것인가” 를 결정하는 정책 엔진에 가깝습니다.

그 중심에 있는 개념이 바로 Predicate(조건자) 입니다. 🧩

✅ Predicate란 무엇인가?

Predicate는 요청이 특정 Route에 매핑될 수 있는지를 판단하는
👉 Boolean 판별식(true / false) 입니다.

SCG의 Predicate는 Java 8의 함수형 인터페이스인
java.util.function.Predicate<T> 를 기반으로 설계되었으며,

📥 입력: ServerWebExchange (요청의 모든 정보)
📤 출력: true 또는 false

즉, HTTP 요청의 모든 요소를 조건으로 활용할 수 있습니다.

• 헤더(Header)
• 쿼리 파라미터(Query)
• URL Path
• 쿠키(Cookie)
• Host
• IP 주소
• 시간(Time)
• 트래픽 비율(Weight)

🔍 1. Predicate의 내부 동작 원리 (아키텍처 관점)

요청이 Gateway에 들어오면 내부에서는 다음과 같은 흐름이 진행됩니다.

🧠 RoutePredicateHandlerMapping의 역할

1️⃣ Gateway는 모든 Route 목록을 순회합니다
2️⃣ 각 Route에 정의된 Predicate들을 순차 실행합니다
3️⃣ Predicate 결과가 true인 Route만 후보로 남습니다

⚙️ 핵심 메커니즘 정리

✔ 평가(Evaluation)

Predicate<ServerWebExchange> → true / false

요청 정보 전체를 담은 ServerWebExchange 를 기준으로 판단합니다.

✔ 조합(Composition)

하나의 Route에 여러 Predicate가 있다면?

predicates:
  - Path=/api/**
  - Method=GET
  - Header=X-Auth, .*

➡ 내부적으로는 다음과 같이 동작합니다.

predicate1.and(predicate2).and(predicate3)

📌 모두 만족해야 Route 매칭 성공

✔ 단락 평가(Short-Circuit) ⚡

• 앞 Predicate가 false → ❌ 즉시 중단
• 불필요한 조건 평가를 하지 않아 성능 최적화

➡ 대규모 트래픽 환경에서 매우 중요한 특성입니다.

🧱 2. 주요 내장 Predicate Factory 정리

SCG는 실무에서 자주 쓰는 조건들을 Factory 패턴으로 제공하고 있습니다.

Predicate	설명	예시
🧭 Path	URL 경로 매칭 (Ant 패턴)	- Path=/api/v1/user/**
📮 Method	HTTP 메서드 검사	- Method=GET, POST
🏷 Header	헤더 존재 / 정규식 매칭	- Header=X-Request-Id, \d+
🔍 Query	쿼리 파라미터 조건	- Query=type, gold
🍪 Cookie	쿠키 값 정규식 매칭	- Cookie=auth, .*
🌐 Host	Host 헤더 매칭	- Host=**.example.com
🧱 RemoteAddr	IP / CIDR 대역 검사	- RemoteAddr=192.168.1.0/24
⚖️ Weight	가중치 기반 트래픽 분산	- Weight=service, 95

⏰ 3. 전문가들이 쓰는 Predicate 활용 기법

⌛ 시간 기반 라우팅 (Before / After / Between)

이벤트, 프로모션, 점검 시간 제어에 매우 유용합니다.

- id: event-route
  uri: lb://event-service
  predicates:
    - After=2024-01-01T00:00:00+09:00[Asia/Seoul]
    - Before=2024-01-31T23:59:59+09:00[Asia/Seoul]

📌 이 기간이 아니면 Route 자체가 존재하지 않는 것처럼 동작합니다.

🧩 커스텀 Predicate 작성 (실무 핵심)

기본 Predicate로 해결되지 않는 경우
👉 Custom RoutePredicateFactory 를 직접 구현합니다.

@Component
public class MyCustomRoutePredicateFactory
        extends AbstractRoutePredicateFactory<MyCustomRoutePredicateFactory.Config> {

    public MyCustomRoutePredicateFactory() {
        super(Config.class);
    }

    @Override
    public Predicate<ServerWebExchange> apply(Config config) {
        return exchange -> {
            String customHeader =
                exchange.getRequest().getHeaders().getFirst("X-Custom");
            return config.getValue().equals(customHeader);
        };
    }

    public static class Config {
        private String value;
        // getter / setter
    }
}

📌 활용 예

• 특정 고객 등급
• A/B 테스트 플래그
• JWT Claim 값 기반 라우팅
• 외부 시스템 상태 기반 분기

⚠️ 4. 설계 시 반드시 알아야 할 Best Practices

🥇 1. Route 우선순서(Order)는 생명이다

/api/**       (포괄적)
/api/v1/**    (구체적)

✔ 해결 방법

• 더 구체적인 Route를 위에 배치
• 또는 order 값을 더 작게 설정

🧮 2. 정규식은 성능을 갉아먹는다

• Header / Cookie Predicate는 요청마다 실행
• 복잡한 정규식 = CPU 비용 증가 🔥

➡ 반드시 부하 테스트로 검증

🚀 3. Weight Predicate = 배포 전략의 핵심

- id: v1
  predicates:
    - Weight=service, 90

- id: v2
  predicates:
    - Weight=service, 10

🎯 별도 로드밸런서 없이도 가능

• Canary Deployment
• Blue-Green Deployment
• 점진적 롤아웃

🧠 마무리 정리

✅ Predicate는 단순한 조건이 아닙니다
👉 Gateway의 정책 결정 엔진입니다.

• 요청 흐름 제어
• 트래픽 분산
• 배포 전략
• 보안 및 접근 제어

모두 Predicate에서 시작됩니다. 🚦