스프링에서 클라이언트로 데이터 전달 시 한글이 깨지는 이슈 (ISO-8859-1)

안녕하세요, 최근 클라이언트(Vue) 와 서버(Spring Boot) 연동 시 서버에서 한글 데이터를 전달하면 클라이언트에서 한글이 깨지는 이슈가 발생했었는데요, 이와 관련하여 간략히 정리해 보았습니다.

 

 

 

원인

HttpMessageConverter 인터페이스는 Spring에서 HTTP request, response 를 변환해 주는 인터페이스인데요, 해당 포스팅을 이해하는데 필요한 내용이라 간략하게만 설명하고 넘어가겠습니다.

 

스프링에서 흔히 사용하는 @RestController 어노테이션에 포함되어 있는 @ResponseBody 어노테이션을 사용할 경우, HttpMessageConverter 이 동작하고 반환 타입에 따라 적절한 구현체가 사용이 됩니다.

 

대표적으로는 ByteArrayHttpMessageConverter, StringHttpMessageConverter, MappingJackson2HttpMessageConveter 등등의 구현체가 존재합니다.

 

 

현재 프로젝트에서 Spring Security를 사용하고 있고, 인증이 성공한 경우와 실패한 경우의 인터페이스인 AuthenticationSuccessHandler, AuthenticationFailureHandler 를 구현한 구현체의 대략적인 코드는 다음과 같습니다.

위 코드 중 ~Success, ~Failure 메서드에서는 response.getWriter().write() 메서드의 파라미터에는 String 타입이 들어가는데요,

 

따라서 HttpMessageConverter 인터페이스의 구현체인 StringHttpMessageConverter 클래스가 동작하게 됩니다.

 

해당 클래스에서 기본 Charset 이 ISO-8859-1 로 설정되어 있기 때문에, 따로 설정해 주지 않으면 클라이언트에서는 전달받은 한글이 깨지는 문제가 발생하게 됩니다.

 

테스트해보면 클라이언트에서는 아래처럼 한글이 깨져서 나오게 됩니다.

 

네트워크 탭에서도 확인해보면 응답 헤더의 Content-Type 의 charset 이 ISO-8859-1 입니다.

 

 

 

 

해결책

더 많은 방법이 존재할 수 있겠지만, 제가 찾은 방법은 크게 3가지 정도 존재할 것 같아요.

 

1. properties(yml) 파일에 server 의 인코딩을 강제로 UTF-8 로 설정하기

server:
  servlet:
    encoding:
      force-response: true
      charset: UTF-8

 

 

2. AuthenticationSuccessHandler, AuthenticationFailureHandler 인터페이스의 구현체에서 인코딩 설정하기

    @Override
    public void onAuthenticationFailure(HttpServletRequest request,
                                        HttpServletResponse response,
                                        AuthenticationException exception) throws IOException {

        ...

	// 인코딩 설정
        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
        
        ...
    }

 

 

3. WebMvcConfigurer 인터페이스를 구현한 클래스

@Configuration
@EnableWebMvc
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        StringHttpMessageConverter converter = new StringHttpMessageConverter(StandardCharsets.UTF_8);
        converter.setDefaultCharset(StandardCharsets.UTF_8);

        converters.add(converter);
        
        // HTTP Response 에서 JSON 변환도 필요할 경우 추가
        converters.add(new MappingJackson2HttpMessageConverter());
    }
}

 

위 방법 중 하나로 설정하면 해결이 되는데요, 저는 2번 방식으로 적용을 했습니다.

1번의 경우, 전역으로 설정하기에 혹시 모를 문제가 존재할 수 있을 것 같았고,

3번의 경우 Config 클래스를 굳이 만들 필요도 없다고 생각했습니다.

 

 

 

테스트 해보면 아래와 같이 한글이 안깨지고, Content-Type 의 charset도 정상적으로 UTF-8로 나오는 것을 확인할 수 있습니다.