SpringCloudGateway를 사용하다 보면 가장 먼저 헷갈리는 개념 중 하나가 GlobalFilter와 GatewayFilter의 차이다. 둘 다 요청과 응답을 가로채 로직을 수행하는 필터라는 점에서는 같지만, 적용 범위와 실행 목적, 설계 의도가 명확하게 다르다. 이 글에서는 SpringCloudGateway에서 제공하는 두 필터의 차이를 구조 관점에서 정리하고, 어떤 상황에서 어떤 필터를 선택해야 하는지 기준을 잡아본다.
SpringCloudGateway GlobalFilter 개념
SpringCloudGateway GlobalFilter는 말 그대로 게이트웨이를 통과하는 모든 요청과 응답에 공통적으로 적용되는 필터다. Route 매칭 여부와 상관없이, Gateway를 거치는 순간 GlobalFilter 체인은 항상 실행된다. 이 특징 때문에 GlobalFilter는 시스템 전반에 영향을 주는 공통 관심사를 처리하는 용도로 사용된다.
대표적인 예로는 로깅, 트레이싱, 공통 헤더 추가, 요청 시작·종료 시간 측정, 공통 인증 전처리 등이 있다. GlobalFilter는 특정 도메인이나 특정 라우트에 종속되지 않기 때문에 “이 요청이 어디로 가든 반드시 수행되어야 하는 로직”에 적합하다. 실제로 SpringCloudGateway 내부에서도 몇 가지 기본 GlobalFilter들이 먼저 등록되어 동작한다.
구조적으로 GlobalFilter는 Ordered 인터페이스를 함께 구현하여 필터 실행 순서를 제어한다. 순서 값이 작을수록 먼저 실행되며, pre 단계에서 먼저 실행된 필터는 post 단계에서는 나중에 실행된다. 이 특성 때문에 GlobalFilter는 게이트웨이 전체 흐름의 전·후를 감싸는 형태가 된다. 주의할 점은 GlobalFilter 안에서 라우트별 분기 로직을 과도하게 넣는 것이다. 이 경우 필터의 책임이 불명확해지고, GatewayFilter와의 역할 경계가 무너지게 된다.
SpringCloudGateway GatewayFilter 개념
GatewayFilter는 특정 라우트에만 적용되는 필터다. 즉, 요청이 어떤 Route와 매칭되었는지가 먼저 결정되고, 그 이후 해당 Route에 등록된 GatewayFilter 체인이 실행된다. 이 점이 GlobalFilter와 가장 큰 차이다. GatewayFilter는 “이 라우트에 대해서만 수행할 로직”을 담기 위한 장치다.
예를 들어 특정 API 그룹에만 JWT 검증을 적용하거나, 특정 도메인에만 헤더를 추가하거나, 특정 경로에만 요청 본문을 변형해야 하는 경우가 이에 해당한다. GatewayFilter는 라우트 정의 시 filters 블록에 명시적으로 등록되며, 해당 라우트가 매칭되지 않으면 아예 실행되지 않는다. 이 덕분에 불필요한 필터 실행을 줄이고, 라우트별 정책을 명확하게 분리할 수 있다.
GatewayFilter는 팩토리 패턴을 기반으로 설계되어 있다. GatewayFilterFactory를 상속받아 구현하며, Config 클래스를 통해 외부 설정 값을 주입받을 수 있다. 이를 통해 동일한 필터 로직을 서로 다른 설정으로 여러 라우트에 재사용할 수 있다. GatewayFilter는 구조적으로 “라우팅 이후의 정책 처리”에 초점을 맞춘 필터이며, GlobalFilter보다 훨씬 도메인 친화적인 성격을 가진다.
SpringCloudGateway 필터 선택 기준
GlobalFilter와 GatewayFilter 중 무엇을 선택할지는 기능의 성격을 기준으로 판단하는 것이 가장 명확하다. 게이트웨이를 통과하는 모든 요청에 대해 무조건 실행되어야 한다면 GlobalFilter가 적합하다. 반대로 특정 라우트나 특정 API 그룹에만 적용되어야 한다면 GatewayFilter를 선택하는 것이 옳다.
실무에서 자주 발생하는 실수는 모든 필터를 GlobalFilter로 처리하려는 것이다. 처음에는 편해 보이지만, 라우트가 늘어나고 정책이 복잡해질수록 조건 분기가 난무하게 되고 유지보수가 급격히 어려워진다. GatewayFilter는 이러한 문제를 방지하기 위해 존재하는 개념이라고 보는 편이 맞다.
정리하면 GlobalFilter는 “게이트웨이 레벨의 공통 인프라 로직”, GatewayFilter는 “라우트 레벨의 정책 로직”이라고 구분할 수 있다. 두 필터는 대체 관계가 아니라 보완 관계다. GlobalFilter에서 전체 흐름을 제어하고, GatewayFilter에서 세부 정책을 처리하는 구조가 SpringCloudGateway가 의도한 설계 방향이다. 이 기준을 명확히 잡아두면 게이트웨이 설계가 훨씬 안정적으로 유지된다.