[TroubleShooting] 왜 우리는 WebFlux를 선택할 수밖에 없었나

👀 현재 상황 및 배경 설명

우리는 MSA 환경에서 각 서버에서 활용할 수 있는 공통 모듈을 도입하려 했다.

• 각 서버는 공통 모듈(common-module)을 통해 공통 로직을 공유하고 있으며,
• 클라이언트의 요청은 Spring Cloud Gateway를 통해 내부 서비스로 라우팅된다.

 

 

🚨 문제 상황

초기 개발 당시, 우리는 익숙한 Spring MVC 기반으로 서비스를 구성하고 있었다. 그러나 Spring Cloud Gateway에 인증 필터를 적용하는 과정에서 문제가 발생했다. 가장 핵심적인 인증 필터가 제대로 동작하지 않았던 것이다.

특정 토큰을 통해 사용자 정보를 추출해 다른 서버로 전파하려 했지만, 사용자 정보가 null인 상태로도 필터가 그대로 통과되는 현상이 나타났다. 이를 통해 필터 로직 자체가 실제로 실행되지 않고 있었음을 확인할 수 있었다.

 

 

✏️ 원인 분석

Spring Cloud Gateway 공식 문서에 대문짝만 하게 명시되어 있었다. Spring Cloud Gateway는 WebFlux 기반으로 동작하며, Servlet 환경에서는 작동하지 않는다.

 

 

🔨 해결 방법

🔽 Spring Cloud Gateway 필터

@Component
public class PassportFilter extends AbstractGatewayFilterFactory<Object> {

    private static final String AUTHORIZATION_HEADER = "Authorization";
    private static final String BEARER_PREFIX = "Bearer ";
    private static final String PASSPORT_HEADER = "X-Passport";

    private final WebClient webClient = WebClient.create();

    @Value("${passport.server.url}")
    private String passportServerUrl;

    public PassportFilter() {
        super(Object.class);
    }

    @Override
    public GatewayFilter apply(Object config) {
        return (exchange, chain) -> {
            String authHeader = exchange.getRequest().getHeaders().getFirst(AUTHORIZATION_HEADER);

            // 1) JWT가 있으면 Passport Server Call
            if (authHeader != null && authHeader.startsWith(BEARER_PREFIX)) {
                String jwt = authHeader.substring(BEARER_PREFIX.length());
                return getPassportFromPassportServer(exchange, chain, jwt);
            }

            // 2) JWT가 없으면 401
            return respondWithUnauthorized(exchange);
        };
    }

    /**
     * JWT를 통해 Passport 발급
     */
    private Mono<Void> getPassportFromPassportServer(ServerWebExchange exchange, GatewayFilterChain chain, String jwt) {
        return webClient.post()
                .uri(passportServerUrl + "/passports?jwt=" + jwt)
                .retrieve()
                .bodyToMono(PassportResponseDto.class)
                .flatMap(response -> {
                    // Passport 발급 실패
                    if (response.getResult() == null || response.getResult().getPassport() == null) {
                        return respondWithUnauthorized(exchange);
                    }

                    // 발급된 Passport를 X-Passport 헤더로 설정
                    ServerWebExchange mutated = exchange.mutate()
                            .request(r -> r.headers(h -> h.set(PASSPORT_HEADER, response.getResult().getPassport())))
                            .build();

                    // 다음 필터로 진행
                    return chain.filter(mutated);
                })
                .onErrorResume(e -> respondWithUnauthorized(exchange));
    }

    /**
     * Unauthorized 응답
     */
    private Mono<Void> respondWithUnauthorized(ServerWebExchange exchange) {
        exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
        return exchange.getResponse().setComplete();
    }
}

위 코드는 Passport 도입으로 인해 다소 복잡하게 느껴질 수 있으니 참고만 바란다. 관련 내용에 관심 있으신 분들은 여기를 참고하시면 도움이 될 것 같다.

우리는 Gateway 서버에서는 공통 모듈에 대한 의존성을 제거하고, WebFlux 기반으로 인증 서버와 통신하는 방식을 선택했다. 즉, Gateway는 WebClient를 사용해 비동기 방식으로 인증 서버에 요청을 보내고, 인증이 완료된 사용자 정보를 각 내부 서비스로 전달하는 구조로 구현했다.

 

이와 동시에, 공통 모듈은 다른 서비스들에서는 그대로 활용하면서 Spring MVC 방식을 유지할 수 있도록 하여, Gateway는 WebFlux, 내부 서비스는 MVC라는 구조를 자연스럽게 분리해 냈다.

 

 

🔍 결과 관찰

도입 이후, 전반적인 인증 흐름이 WebClient를 통한 비동기 처리 방식으로 안정화되었다. Spring Cloud Gateway의 필터 로직 또한 WebFlux 체계 위에서 정상적으로 작동하면서, 기존에 발생하던 사용자 정보 누락 문제도 말끔히 해결되었다. 공통 모듈을 기반으로 인증 로직을 일관되게 관리할 수 있게 되면서, 서비스 간 인증 처리의 유지보수성도 크게 향상되었다. 인증 서버와의 통신 역시 WebClient 덕분에 병렬로 빠르고 효율적으로 처리되었다.

 

 

💡 고찰

WebFlux에 대한 이해가 부족한 상태에서 디버깅을 진행하다 보니 예상보다 많은 어려움을 겪었다. 하지만 결국 공식 문서 안에 모든 해답이 있었다.

 

소켓 기반의 실시간 서비스나 Gateway + 인증 서버 구조에서는 WebFlux가 사실상 필수라는 점을 알 수 있었다. Mono, Flux와 같은 비동기 흐름에 대한 이해가 쌓이면 WebFlux의 동작 원리를 더 쉽게 파악할 수 있을 것 같고, 이를 위해 빠른 시일 내에 깊이 있게 학습할 계획이다.

 

 

📍 참고 자료

• Spring 공식 문서 - Spring Cloud Gateway