SpringCloudGateway를 사용하다 보면 필터는 정상적으로 등록했는데 의도한 순서대로 실행되지 않거나, pre 로직과 post 로직의 실행 타이밍이 헷갈리는 경우가 많다. 이는 SpringCloudGateway의 필터 구조가 단순한 체인 구조가 아니라 라우팅 단계와 결합된 실행 흐름을 가지기 때문이다. 이 글에서는 SpringCloudGateway의 요청 흐름을 기준으로 필터가 어떤 순서로 실행되는지 정리한다.
SpringCloudGateway 필터 실행흐름
SpringCloudGateway의 필터 실행 순서를 이해하려면 요청이 게이트웨이에 들어온 순간부터 다운스트림 서비스로 전달되기까지의 흐름을 먼저 살펴봐야 한다. 클라이언트 요청이 들어오면 가장 먼저 RoutePredicateHandlerMapping이 동작한다. 이 단계에서는 아직 필터가 실행되지 않는다. 요청이 어떤 Route와 매칭되는지 판단하는 단계다.
Route가 결정되면 GatewayWebHandler가 호출되고, 이 시점부터 본격적으로 필터 체인이 구성된다. 필터 체인은 크게 Route Predicate Filter, GlobalFilter, GatewayFilter, HttpHeadersFilter 순서로 정렬된다. 이 정렬은 단순 등록 순서가 아니라 내부 우선순위와 Ordered 값에 의해 결정된다.
pre 단계에서는 위 순서대로 필터가 실행된다. 즉, 먼저 GlobalFilter의 pre 로직이 실행되고, 그 다음 GatewayFilter의 pre 로직이 실행된다. 모든 pre 필터가 실행된 후 요청은 실제 목적지 서비스로 전달된다. 응답이 돌아오면 흐름은 반대로 진행된다. GatewayFilter의 post 로직이 먼저 실행되고, 그 다음 GlobalFilter의 post 로직이 실행된다. 이 구조는 스택처럼 동작하며, 이 점을 이해하지 못하면 post 로직 실행 순서에서 혼란이 생기기 쉽다.
SpringCloudGateway GlobalFilter 순서
GlobalFilter는 게이트웨이를 통과하는 모든 요청과 응답에 적용되는 필터다. GlobalFilter는 Ordered 인터페이스를 통해 명시적으로 실행 순서를 지정할 수 있다. Order 값이 작을수록 먼저 실행되며, pre 단계에서는 작은 값부터, post 단계에서는 큰 값부터 실행된다.
예를 들어 Order가 0인 GlobalFilter와 Order가 10인 GlobalFilter가 있다면, pre 단계에서는 0 → 10 순서로 실행된다. 하지만 post 단계에서는 10 → 0 순서로 실행된다. 이 구조 때문에 GlobalFilter는 요청의 시작과 끝을 감싸는 형태가 된다. 로그 기록, 공통 헤더 처리, 요청·응답 시간 측정 같은 로직이 GlobalFilter에 적합한 이유가 여기에 있다.
주의할 점은 GlobalFilter에서 라우트별 조건 분기를 과도하게 넣는 것이다. GlobalFilter는 라우트 매칭 이후에도 실행되지만, 설계 의도는 “전체 공통 처리”에 있다. 특정 API나 도메인에만 적용할 정책을 GlobalFilter에 넣기 시작하면 필터 책임이 모호해지고 유지보수가 어려워진다. GlobalFilter의 순서를 제어할 때는 게이트웨이 전체 흐름에서 어디에 위치해야 하는지만 고려하는 것이 바람직하다.
SpringCloudGateway GatewayFilter 순서
GatewayFilter는 Route에 종속된 필터다. 즉, 요청이 특정 Route와 매칭된 이후에만 실행된다. GatewayFilter는 Route 정의 시 filters 블록에 명시적으로 등록되며, 등록된 순서와 Order 값에 따라 실행 순서가 결정된다. 기본적으로 GatewayFilter는 GlobalFilter보다 안쪽에서 실행된다.
pre 단계 기준으로 보면, GlobalFilter의 pre 로직이 모두 실행된 뒤 GatewayFilter의 pre 로직이 실행된다. 응답 단계에서는 반대로 GatewayFilter의 post 로직이 먼저 실행되고, 그 다음 GlobalFilter의 post 로직이 실행된다. 이 구조 덕분에 GatewayFilter는 특정 라우트의 요청·응답을 세밀하게 제어할 수 있다.
GatewayFilter 역시 Ordered를 통해 라우트 내부에서의 실행 순서를 조정할 수 있다. JWT 검증, 헤더 변형, 요청 본문 수정 등 라우트별 정책은 GatewayFilter에서 처리하는 것이 구조적으로 가장 안정적이다. 특히 여러 GatewayFilter를 하나의 라우트에 적용할 경우 필터 순서가 결과에 직접적인 영향을 주기 때문에 명시적인 Order 관리가 중요하다. SpringCloudGateway의 필터 실행 순서를 정확히 이해하면 의도하지 않은 인증 누락이나 필터 미적용 문제를 예방할 수 있다.