[Spring] WebClient에서 URI.create()를 사용하지 않을 때 500 Internal Server Error가 발생하는 이유

 

ㅁ 들어가며

ㅇ Spring WebClient에서 URI.create()를 사용하지 않을 때 500 Internal Server Error가 발생하는 이유는, URI를 문자열로 직접 넘기는 과정에서 URI의 형식이나 인코딩, baseUrl과의 조합 등에서 문제가 생길 수 있기 때문이다.

 

ㅁ 에러 메시지

org.springframework.web.reactive.function.client.WebClientResponseException$InternalServerError: 500 Internal Server Error

ㅇ 에러 메시지만으로는 당장 원인을 분석하기 쉽지 않다.

 

ㅁ 원인 분석

Spring WebClient에서 uri() 메서드에 URI 문자열이 아닌, 잘못된 타입이나 형식의 값을 넘기거나, URI.create()를 사용하지 않고 단순 문자열을 넘길 때 내부적으로 URI 파싱에 실패하거나, baseUrl과의 조합이 꼬여서 잘못된 요청이 발생할 수 있다. 이로 인해 서버에서 500 Internal Server Error가 발생할 수 있다. 실제로 WebClient는 다음과 같이 URI를 지정할 수 있다.

• uri(String uri): baseUrl이 지정되어 있으면 상대 경로로 동작
• uri(URI uri): baseUrl 무시, 절대 URI로 동작
• uri(Function uriFunction): UriBuilder를 활용해 동적으로 URI 생성

문자열로 넘기는 경우 Spring이 내부적으로 자동으로 URI로 변환하지만, 쿼리 파라미터나 특수문자가 포함되어 있거나, baseUrl과의 조합이 맞지 않으면 오류가 발생할 수 있다. 반면, URI.create()를 명시적으로 사용하면 이런 문제를 방지할 수 있다.

 

ㅁ 해결 방법

ㅇ URI 생성 방식 명확히 하기

• baseUrl을 사용한다면, 상대 경로 문자열만 넘기면 된다.
• 절대 경로를 직접 지정하려면 URI.create()를 사용해 URI 객체를 만들어 넘겨야 한다. 

// baseUrl이 세팅된 경우 (상대 경로)
webClient.get()
    .uri("/harmony/v1/contents/list.json")
    .retrieve()
    .bodyToMono(String.class);

// baseUrl 없이 절대 경로를 직접 지정
webClient.get()
    .uri(URI.create("http://dapi.kakao.com/harmony/v1/contents/list.json"))
    .retrieve()
    .bodyToMono(String.class);

이렇게 하면 Spring이 URI 파싱에서 오류를 내지 않고, 올바른 요청을 보낸다.

 

ㅇ 쿼리 파라미터가 있을 때는 UriBuilder 사용 권장

webClient.get()
    .uri(uriBuilder -> uriBuilder
        .path("/harmony/v1/contents/list.json")
        .queryParam("key", "value")
        .build())
    .retrieve()
    .bodyToMono(String.class);

이 방식은 쿼리 파라미터, 경로 변수 등 복잡한 URI를 안전하게 만들 수 있다.

 

ㅇ 에러 핸들링 추가

WebClient는 4xx, 5xx 응답 시 WebClientResponseException을 발생시키므로, 에러 핸들링을 추가해 원인을 로그로 남겨야한다..

webClient.get()
    .uri(URI.create("http://dapi.kakao.com/harmony/v1/contents/list.json"))
    .retrieve()
    .bodyToMono(String.class)
    .doOnError(WebClientResponseException.class, e -> {
        log.error("WebClient error: {}, body: {}", e.getStatusCode(), e.getResponseBodyAsString());
    });

 

ㅁ 마무리

WebClient에서 URI를 지정할 때는 baseUrl과 uri() 파라미터의 관계를 명확히 이해하고, 혼동이 있을 때는 URI.create()나 UriBuilder를 사용해 URI를 명확히 한다. 단순 문자열 대신 URI.create()를 사용하면 URI 파싱 오류로 인한 500 Internal Server Error를 방지할 수 있다