Webflux에서 Error를 다루는방법(Handling Errors in Spring WebFlux)

원본 글: https://www.baeldung.com/spring-webflux-errors

Spring WebFlux에서 에러를 다루는 여러 전략들에 대해 장점을 파악하고 소개합니다.

1. Setting Up the Example

글에서는 Maven을 썼지만 저는 gradle로 초기셋팅을 진행하겠습니다.

implementation 'org.springframework.boot:spring-boot-starter-webflux'

해당 의존성을 추가해줍니다.
이 글에서 예제는 ${username} 파라미터를 쿼리형태로 받아서 "Hello ${username}"을 반환할 겁니다.

먼저 /hello 요청에 대한 router function을 생성합니다.

@Configuration
public class UserRouter {

    @Bean
    public RouterFunction<ServerResponse> routes(Handler handler) {
        return RouterFunctions.route(RequestPredicates.GET("/hello")
                .and(RequestPredicates.accept(MediaType.TEXT_PLAIN)),handler::함수);
    }
}

여기서 Handler는 요청을 처리하는 직접만든 클래스입니다. 이에 대한 코드도 작성해줍니다.

@Component
public class Handler {

    public Mono<ServerResponse> handleWithGlobalErrorHandler(ServerRequest serverRequest) {
        return ServerResponse
                .ok()
                .body(sayHello(serverRequest), String.class);
    }

    public Mono<String> sayHello(ServerRequest serverRequest) {
        try {
            return Mono.just("Hello " + serverRequest.queryParam("name").get());
        } catch (Exception e) {
            return Mono.error(e);
        }
    }
}

• handleWithGlobalErrorHandler() 함수는 sayHello()함수를 호출하면서 해당 함수가 리턴하는 문자열을 ServerResponse 바디에 담아 반환합니다.
• sayHello() 함수는 /hello?username=minseok과 같은 요청에 대해서는 정상 응답하지만, /hello와 같은 username을 빼먹은 응답에 대해서는 에러를 반환합니다.

> curl --location 'http://localhost:8080/hello?username=minseok'                                 
Hello minseok% 
> curl --location 'http://localhost:8080/hello'                                                 
{"timestamp":"2025-02-24T00:17:53.037+00:00","path":"/hello","status":500,"error":"Internal Server Error","requestId":"728c0a52-1"}%   

이렇게 에러가 발생했을때 이를 다룰수 있는 여러 방법들을 한 번 알아봅니다.

2. Handling Errors at a Functional Level

이러한 에러핸들링을 위해서 Mono, Flux에서 기본적으로 제공하는 두가지 내장 함수가 있습니다. 이를 확인해봅니다.

2.1 Handling Errors With onErrorReturn

onErrorReturn() 함수를 사용하면 에러가 발생했을때 고정된 값을 반환할 수 있습니다.

public Mono<ServerResponse> handleWithErrorReturn(ServerRequest serverRequest) {
    return sayHello(serverRequest)
            .onErrorReturn("Hello Stranger")
            .flatMap(s -> ServerResponse.ok()
                    .contentType(MediaType.TEXT_PLAIN)
                    .bodyValue(s));
}

> curl --location 'http://localhost:8080/hello'                                                 
Hello Stranger%   

• flatMap을 사용한 이유는 Mono<String> 값을 Mono<ServerResponse>로 변환하기 위함입니다.

2.2 Handling Errors With onErrorResume

onErrorResume을 사용하여 오류를 처리할 수 있는 세 가지 방법이 있습니다.

• 동적으로 에러값을 반환
• 다른 경로로 대체 실행
• 에러를 다른 커스텀한 exception으로 전달

먼저 동적으로 에러값을 반환하는 방법입니다.

public Mono<ServerResponse> handleWithErrorResumeAndDynamicFallback(ServerRequest request) {
    return sayHello(request)
            .flatMap(s -> ServerResponse.ok()
                    .contentType(MediaType.TEXT_PLAIN)
                    .bodyValue(s))
            .onErrorResume(e -> Mono.just("Error " + e.getMessage())
                    .flatMap(s -> ServerResponse.ok()
                            .contentType(MediaType.TEXT_PLAIN)
                            .bodyValue(s)));
}

> curl --location 'http://localhost:8080/hello'                                                 
Error No value present                                                                                                                                                                  

Mono.just()구문안에 동적으로 에러메시지를 담아서 반환하는 코드입니다.
다음은 에러가 발생했을때 다른 함수를 호출하도록 변경해봅니다.(fallback방식)

public Mono<ServerResponse> handleWithErrorResumeAndFallbackMethod(ServerRequest request) {
    return sayHello(request)
            .flatMap(s -> ServerResponse.ok()
                    .contentType(MediaType.TEXT_PLAIN)
                    .bodyValue(s))
            .onErrorResume(e -> sayHelloFallback()
                    .flatMap(s -> ServerResponse.ok()
                            .contentType(MediaType.TEXT_PLAIN)
                            .bodyValue(s)));
}

private Mono<String> sayHelloFallback() {
    return Mono.just("Hello, Stranger");
}

> curl --location 'http://localhost:8080/hello'                                                 
Hello, Stranger%           

마지막으로 에러를 잡아 다른 커스텀한 에러로 전달하는 방식을 확인해봅시다.

public Mono<ServerResponse> handleWithErrorResumeAndCustomException(ServerRequest request) {
    return ServerResponse.ok()
            .body(sayHello(request)
                    .onErrorResume(e -> Mono.error(new NameRequiredException(
                            HttpStatus.BAD_REQUEST,
                            "username is required", e))), String.class);
}
public class NameRequiredException extends ResponseStatusException {

    public NameRequiredException(HttpStatusCode status, String message, Throwable e) {
        super(status, message, e);
    }
}

이렇게하면 에러발생시 커스텀한 exception에 메시지를 던져줄 수 있습니다.

> curl --location 'http://localhost:8080/hello'                                                  
{"timestamp":"2025-02-24T00:47:02.176+00:00","path":"/hello","status":400,"error":"Bad Request","requestId":"a1adc252-3"}%     

다만 위처럼 작성하면 응답본문에는 메시지가 포함되지 않습니다.

3. Handling Errors at a Global Level

위의 예시들은 모두 함수에서 에러를 핸들링하였습니다.

전역 에러 핸들러를 사용해서 Global Level에서의 에러를 핸들링할 수 있습니다. 2가지 절차를 밟아야합니다.

Global Error Response 속성을 직접 커스텀해줘야하는데 이는 DefaultErrorAttributes 클래스를 상속받아서 만들 수 있습니다.

@Component
public class GlobalErrorAttributes extends DefaultErrorAttributes {

    public Map<String, Object> getErrorAttributes(ServerRequest request, ErrorAttributeOptions options) {
        Map<String,Object> map = super.getErrorAttributes(request,options);
        map.put("status", HttpStatus.BAD_REQUEST);
        map.put("message", "please provide a name");
        return map;
    }
}

다음은 AbstractErrorWebExceptionHandler클래스를 상속받아서 Global Error Handler를 구현합니다.

@Component
@Order(-2)
public class GlobalErrorWebExceptionHandler extends AbstractErrorWebExceptionHandler {

    public GlobalErrorWebExceptionHandler(
            GlobalErrorAttributes g, ApplicationContext applicationContext,
            ServerCodecConfigurer serverCodecConfigurer) {
        super(g, new WebProperties.Resources(), applicationContext);
        super.setMessageWriters(serverCodecConfigurer.getWriters());
        super.setMessageReaders(serverCodecConfigurer.getReaders());
    }
    @Override
    protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
        return RouterFunctions.route(
                RequestPredicates.all(), this::renderErrorResponse
        );
    }

    private Mono<ServerResponse> renderErrorResponse(ServerRequest request) {
        Map<String,Object> errorPropertiesMap = getErrorAttributes(request, ErrorAttributeOptions.defaults());

        return ServerResponse.status(HttpStatus.BAD_REQUEST)
                .contentType(MediaType.APPLICATION_JSON)
                //.bodyValue(BodyInserters.fromValue(errorPropertiesMap)); 본문은 이렇게 되어있지만 직렬화가 제대로 안됨.
                .bodyValue(errorPropertiesMap);
    }
}

이 예제에서는 전역 오류 처리기의 우선 순위를 -2로 설정하여 기본 오류 처리기인 DefaultErrorWebExceptionHandler의 우선 순위인 @Order(-1)보다 높게 설정합니다.
errorAttributes 객체는 웹 예외 처리기의 생성자에서 전달된 사용자 정의 오류 속성 클래스의 복사본이 됩니다.
그리고 모든 오류 처리 요청을 renderErrorResponse() 메서드로 라우팅합니다. 최종적으로 오류 세부 정보와 HTTP 상태, 예외 메시지를 포함한 JSON 응답을 생성합니다.
브라우저 클라이언트에는 HTML 형식으로 같은 데이터가 표시됩니다.

> curl --location 'http://localhost:8080/hello'                                                 
{"timestamp":"2025-02-24T01:28:22.627+00:00","path":"/hello","status":"BAD_REQUEST","error":"Bad Request","requestId":"fd1baac9-1","message":"please provide a name"}%  

4. 결론

Spring WebFlux환경에서 에러를 다룰 수 있는 여러 방법에 대해 학습하였습니다.

---

라우트 기반의 에러핸들링하는 방법을 살펴봤고, 전역으로 이를 다루는 법까지 학습하였습니다. 현재 진행하고 있는 프로젝트에 적용하기 좋은 예제였습니다.

다만 설명이 막 친절하진 않았습니다.

예제코드