Spring에서 CharacterEncodingFilter로 UTF-8 적용하기 (web.xml & Java 설정 & Spring Boot)

Spring에서 UTF-8 인코딩 설정이 필요한 이유

스프링 MVC로 웹 애플리케이션을 개발하다 보면, 한글 파라미터가 깨져서 들어오거나 화면에 물음표(???)로 보이는 경험을 한 번쯤 하게 됩니다. 이 경우 가장 먼저 확인해야 할 것이 바로 요청/응답 인코딩 설정입니다.

스프링에서는 CharacterEncodingFilter를 사용해 전체 요청/응답에 대해 일괄적으로 인코딩을 설정할 수 있습니다. 가장 흔히 사용하는 값은 UTF-8입니다.

---

1. web.xml에서 encodingFilter 설정 (레거시 방식)

스프링 MVC(레거시, 서블릿 2.x ~ 3.x)에서 한글이 깨질 때 가장 먼저 적용하던 설정입니다. web.xml의 하단에 다음 필터를 추가합니다.

<filter>
    <filter-name>encodingFilter</filter-name>
    <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>

    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>

    <init-param>
        <param-name>forceEncoding</param-name>
        <param-value>true</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>encodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

설명

• encoding : 사용할 문자 인코딩을 지정합니다. 보통 UTF-8.
• forceEncoding : true로 설정하면
  • 요청(request)의 인코딩을 강제로 UTF-8로 설정
  • 응답(response)에도 UTF-8 인코딩을 강제로 설정
• url-pattern : 모든 요청(/*)에 대해 필터를 적용하겠다는 의미입니다.

기본적으로 위 설정만 추가해도, 스프링 MVC에서 발생하는 대부분의 한글 깨짐 문제는 해결되는 경우가 많습니다.

---

2. Java Config에서 CharacterEncodingFilter 설정하기

최근에는 web.xml 대신 Java Config를 사용하는 프로젝트가 많습니다. 이 경우 필터를 자바 코드로 등록할 수 있습니다.

2-1. 서블릿 3.x + 스프링 Java Config 예시

import org.springframework.web.filter.CharacterEncodingFilter;
import org.springframework.web.WebApplicationInitializer;

import javax.servlet.FilterRegistration;
import javax.servlet.ServletContext;
import javax.servlet.ServletException;

public class WebAppInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext servletContext) throws ServletException {

        CharacterEncodingFilter encodingFilter = new CharacterEncodingFilter();
        encodingFilter.setEncoding("UTF-8");
        encodingFilter.setForceEncoding(true);

        FilterRegistration.Dynamic filter =
                servletContext.addFilter("encodingFilter", encodingFilter);

        filter.addMappingForUrlPatterns(null, false, "/*");
    }
}

구현 내용은 web.xml 설정과 동일하며, 단지 Java 코드로 필터를 등록하는 방식일 뿐입니다.

---

3. Spring Boot에서의 UTF-8 인코딩 처리

Spring Boot를 사용하면 대부분의 경우 CharacterEncodingFilter가 자동 등록됩니다. 기본적으로 UTF-8이 사용되지만, 필요하다면 아래처럼 설정을 명시할 수 있습니다.

3-1. application.properties 설정

spring.web.encoding.charset=UTF-8
spring.web.encoding.enabled=true
spring.web.encoding.force=true

3-2. 직접 Bean 등록 (필요한 경우)

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.filter.CharacterEncodingFilter;

@Configuration
public class EncodingConfig {

    @Bean
    public CharacterEncodingFilter characterEncodingFilter() {
        CharacterEncodingFilter filter = new CharacterEncodingFilter();
        filter.setEncoding("UTF-8");
        filter.setForceEncoding(true);
        return filter;
    }
}

대부분의 Spring Boot 프로젝트는 기본 설정만으로도 UTF-8이 잘 적용되지만, 환경에 따라 명시적으로 설정해 주면 더 안전합니다.

---

4. 그래도 한글이 깨진다면 추가로 확인할 것들

• JSP 파일 상단에 <%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" %> 설정 여부
• DB 커넥션/테이블/컬럼의 Charset이 UTF-8인지 (예: MySQL의 utf8mb4)
• HTTP 응답 헤더의 Content-Type에 charset=UTF-8 포함 여부
• 프론트엔드(HTML, JS)의 <meta charset="UTF-8"> 설정 여부

즉, 서버 단에서 CharacterEncodingFilter만 설정한다고 끝이 아니라, 전체 요청/응답/뷰/DB까지 인코딩이 일관되게 UTF-8로 맞춰져야 한글이 깨지지 않습니다.

---

정리

• 스프링 MVC에서 한글이 깨질 경우 CharacterEncodingFilter를 가장 먼저 확인
• web.xml에서 encodingFilter 설정 → 레거시 프로젝트에서 유효
• Java Config, Spring Boot에서는 필터/설정 Bean으로 UTF-8 강제 적용 가능
• 뷰(JSP/Thymeleaf), DB, HTTP 헤더까지 전 구간 인코딩이 맞아야 완전하게 해결

기본적인 설정이지만, 놓치면 하루 종일 삽질하게 만드는 부분이기도 합니다. 스프링 프로젝트 시작할 때 가장 먼저 UTF-8 인코딩 설정부터 점검해 두시는 것을 추천드립니다.