WebConfig로 해결한 문자 인코딩의 미스터리

Postman 화면

직면한 문제

최근에 SpringBoot에서 작업하면서 이해할 수 없는 상황에 직면했습니다. 제가 사용하고 있는 한글 문자가 제대로 표시되지 않고, 의문표로 뒤덮여 버리는 현상이 나타났습니다. 특히 API 응답에서 한글로 된 메시지가 필요한데, 이 문자들이 온전하게 표현되지 않아 문제가 되었습니다.

문제의 원인

문제는 Spring 프레임워크가 HTTP 응답에 사용하는 기본 문자 인코딩 설정에 있었습니다. Spring Boot는 기본적으로 ISO-8859-1을 사용하는데, 이는 한글 문자를 다루기에 부적합합니다. 인코딩 불일치로 인해 원래 메시지가 알아볼 수 없는 기호로 변해버렸습니다.

해결 방법

이 문제를 해결하기 위해 WebMvcConfigurer를 확장하는 커스텀 WebConfig 클래스를 만들고, extendMessageConverters 메서드를 구현했습니다.

@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
    converters.add(0, new StringHttpMessageConverter(StandardCharsets.UTF_8));
}

UTF-8 문자 집합을 가진 새로운 StringHttpMessageConverter를 컨버터 목록의 맨 앞에 추가함으로써, 제 애플리케이션이 한글 문자를 올바르게 해석하고 표시하도록 보장했습니다.