스프링 클라우드(SPRING CLOUD)의 글로벌 필터(Global Filter)

스프링 클라우드(SPRING CLOUD)의 글로벌 필터(Global Filter)는 Spring Cloud Gateway에서 제공하는 기능으로, 모든 요청에 대해 사전 또는 사후 작업을 수행하는 필터입니다. 이 필터는 애플리케이션 전역적으로 적용되며, 특정 라우트(Route)와 관계없이 동작합니다.

---

1. 글로벌 필터(Global Filter)란?

• Spring Cloud Gateway의 필터는 크게 GlobalFilter와 RouteFilter로 나뉩니다.
  • GlobalFilter: 모든 요청에 대해 동작.
  • RouteFilter: 특정 라우트(Route)에만 적용.

글로벌 필터의 역할

1. 모든 HTTP 요청에 대해 공통 작업 수행.
2. 요청(Request)을 전처리하거나 응답(Response)을 후처리.
3. 로깅, 인증/인가, 헤더 관리, 추적 ID 설정, 성능 모니터링 등과 같은 공통 로직 처리.

---

2. 글로벌 필터 구현 방법

GlobalFilter 인터페이스

Spring Cloud Gateway에서 GlobalFilter는 org.springframework.cloud.gateway.filter.GlobalFilter 인터페이스를 구현하여 사용됩니다.

@Component
public class CustomGlobalFilter implements GlobalFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 요청 전처리
        System.out.println("Global Filter: PRE-Processing");

        return chain.filter(exchange).then(Mono.fromRunnable(() -> {
            // 응답 후처리
            System.out.println("Global Filter: POST-Processing");
        }));
    }
}

구성 요소 설명

• ServerWebExchange:
  • HTTP 요청 및 응답을 캡슐화한 객체.
  • 요청 헤더/파라미터 수정, 응답 처리 등에 사용.
• GatewayFilterChain:
  • 요청을 다음 필터 체인으로 전달.
• Mono<Void>:
  • 비동기 방식으로 필터 작업을 처리.

---

3. 등록된 글로벌 필터의 동작 흐름

1. 요청 흐름:

   • 클라이언트 → 글로벌 필터(전처리) → 라우팅 → 글로벌 필터(후처리) → 응답.

2. 필터 체인:

   • 글로벌 필터는 GatewayFilterChain에 연결되어 순차적으로 실행됩니다.

---

3. 글로벌 필터 사용 사례

3.1 요청 로깅

모든 요청의 URI와 HTTP 메서드를 로깅합니다.

@Component
public class LoggingGlobalFilter implements GlobalFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String requestPath = exchange.getRequest().getURI().getPath();
        String method = exchange.getRequest().getMethodValue();
        System.out.println("Incoming Request: " + method + " " + requestPath);

        return chain.filter(exchange).then(Mono.fromRunnable(() -> {
            System.out.println("Outgoing Response for: " + requestPath);
        }));
    }
}

---

3.2 요청 헤더 추가

모든 요청에 공통 헤더를 추가합니다.

@Component
public class AddHeaderGlobalFilter implements GlobalFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        exchange.getRequest()
                .mutate()
                .header("X-Global-Header", "GlobalHeaderValue")
                .build();
        return chain.filter(exchange);
    }
}

---

3.3 CORRELATION_ID 설정

요청 간의 상관관계를 추적하기 위해 요청에 고유한 CORRELATION_ID를 설정합니다.

@Component
public class CorrelationIdGlobalFilter implements GlobalFilter {

    private static final String CORRELATION_ID = "X-Correlation-ID";

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String correlationId = exchange.getRequest().getHeaders().getFirst(CORRELATION_ID);

        if (correlationId == null) {
            correlationId = UUID.randomUUID().toString();
        }

        exchange.getResponse().getHeaders().add(CORRELATION_ID, correlationId);

        return chain.filter(exchange);
    }
}

---

4. 글로벌 필터와 RouteFilter의 차이

구분	GlobalFilter	RouteFilter
적용 범위	모든 요청에 적용	특정 라우트(Route)에만 적용
설정 방법	GlobalFilter 인터페이스 구현	application.yml 또는 RouteFilter 코드로 정의
주요 사용 사례	공통 작업 (로깅, 인증, 헤더 관리, 추적 ID 설정 등)	특정 서비스 또는 라우트에 대한 작업 (캐싱, 특정 헤더 추가 등)

---

5. 글로벌 필터 실행 순서

필터 순서 지정

Spring Cloud Gateway에서 글로벌 필터는 우선순위(priority)를 지정할 수 있습니다. 우선순위는 Ordered 인터페이스를 구현하여 설정합니다.

@Component
public class OrderedGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        System.out.println("This is an ordered global filter");
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return 1; // 낮은 값일수록 높은 우선순위
    }
}

---

6. Spring Cloud Gateway에서 글로벌 필터 등록 확인

글로벌 필터가 등록되었는지 확인하려면 /actuator/gateway/globalfilters 엔드포인트를 사용합니다.

Actuator 활성화

application.yml에서 Actuator 엔드포인트 활성화:

management:
  endpoints:
    web:
      exposure:
        include: gateway

등록된 글로벌 필터 확인

curl -X GET http://localhost:8080/actuator/gateway/globalfilters

---

7. 주의 사항

1. 비동기 처리:

   • Spring WebFlux 기반이므로, 필터 내부에서 비동기 작업을 올바르게 처리해야 합니다.
   • 블로킹 작업을 사용하면 성능에 악영향을 미칩니다.

2. 필터 체인 관리:

   • 모든 요청에 적용되므로, 잘못된 로직이 들어가면 애플리케이션 전체에 영향을 미칩니다.
   • 필터 체인에서 chain.filter(exchange)를 반드시 호출해야 요청이 다음 단계로 전달됩니다.

3. 우선순위 충돌:

   • 여러 글로벌 필터를 사용하는 경우, 우선순위를 명확히 설정해야 실행 순서가 보장됩니다.

---

결론

Spring Cloud Gateway의 글로벌 필터는 모든 요청에 대해 공통 작업을 처리하는 강력한 도구입니다. 로깅, 인증, 헤더 관리, 성능 모니터링 등 다양한 작업에 활용할 수 있으며, 이를 통해 마이크로서비스 환경에서 효율적이고 일관된 요청 처리가 가능합니다.