[Spring] 스프링 MVC의 심장, web.xml 완벽 분석 (DispatcherServlet, 한글 필터)

🌐 [Spring] 스프링 MVC의 심장, web.xml 완벽 분석 (DispatcherServlet, 한글 필터)

오늘은 스프링 부트(Spring Boot) 없이 전통적인 방식으로 Spring MVC 프로젝트를 구성할 때, 가장 먼저 만나게 되는 파일인 web.xml에 대해 깊이 있게 분석해 보겠습니다.

web.xml은 배포 서술자(Deployment Descriptor, DD)라고 불리며, 웹 애플리케이션이 최초에 구동될 때 WAS(Web Application Server, 예: Tomcat)가 가장 먼저 읽는 설정 파일입니다. 즉, 우리 프로젝트의 모든 요청이 어떻게 처리될지 정의하는 매우 중요한 시작점이죠.

📝 전체 코드 살펴보기

먼저 분석할 web.xml 파일의 전체 코드입니다.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
         http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">

    <display-name>Spring MVC Application</display-name>

    <!-- Spring DispatcherServlet -->
    <servlet>
        <servlet-name>dispatcher</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>/WEB-INF/dispatcher-servlet.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>dispatcher</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

    <!-- Character Encoding Filter -->
    <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>
    </filter>

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

 

📝 핵심 설정 분석

이 파일은 크게 두 가지 핵심적인 역할을 합니다.
    1.Spring MVC의 핵심 엔진인 DispatcherServlet을 등록하고 설정합니다.
    2.모든 요청에 대한 한글 깨짐을 방지하기 위한 CharacterEncodingFilter를 설정합니다.

하나씩 자세히 살펴보겠습니다.

1. DispatcherServlet: 모든 요청을 받는 프론트 컨트롤러

DispatcherServlet은 Spring MVC의 핵심 엔진이자 심장입니다. 클라이언트의 모든 요청을 가장 먼저 받아서 적절한 컨트롤러(@Controller)에게 작업을 위임하는 프론트 컨트롤러(Front Controller) 역할을 합니다.

<servlet> 태그 분석

<servlet>
    <servlet-name>dispatcher</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/dispatcher-servlet.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

• <servlet-name>: 서블릿의 별명을 지정합니다. dispatcher라는 이름으로 아래 매핑 설정에서 사용됩니다.
• <servlet-class>: 서블릿으로 사용할 실제 클래스를 지정합니다. Spring MVC의 핵심인 org.springframework.web.servlet.DispatcherServlet을 등록했습니다.
• <init-param>: 서블릿을 초기화할 때 필요한 파라미터를 설정합니다.
    • contextConfigLocation: DispatcherServlet이 사용할 Spring 설정 파일의 위치를 알려줍니다.
      여기서는 /WEB-INF/dispatcher-servlet.xml 파일을 사용하도록 지정했네요.
      이 파일 안에는 @Controller를 스캔할 패키지 위치나 ViewResolver 같은 빈(Bean) 설정이 들어있습니다.
•<load-on-startup>: WAS가 시작될 때 서블릿을 로드하는 순서를 지정합니다. 값이 1이므로 WAS가 구동되면서 가장 먼저 이 서블릿을 초기화합니다. 이를 통해 첫 요청 시 지연 없이 바로 응답할 수 있습니다.

<servlet-mapping> 태그 분석

<servlet-mapping>
    <servlet-name>dispatcher</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

• <servlet-name>: 위에서 정의한 dispatcher 서블릿에 대한 매핑임을 알려줍니다.
• <url-pattern>/</url-pattern>: 가장 중요한 부분입니다. 이 설정은 모든 요청(http://.../)을 DispatcherServlet이 처리하도록 만듭니다. (정확히는 JSP 요청을 제외한 모든 요청)

💡 Tip: url-pattern을 /*로 설정하면 JSP 파일 요청까지 가로채서 뷰(View)가 제대로 렌더링되지 않는 문제가 발생할 수 있습니다. 따라서 Spring MVC에서는 일반적으로 /를 사용합니다.

2. CharacterEncodingFilter: 한글 깨짐 방지를 위한 필수 설정

웹 애플리케이션에서 한글로 된 데이터를 POST 방식으로 전송할 때, 별도 설정이 없으면 글자가 깨지는 현상이 발생합니다. 이를 방지하기 위해 모든 요청에 대해 UTF-8 인코딩을 강제하는 필터를 설정합니다.

<!-- Character Encoding Filter -->
<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>
</filter>

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

• <filter-class>: Spring에서 제공하는 CharacterEncodingFilter를 사용합니다.
• <init-param>: 필터에 encoding 값을 UTF-8로 설정합니다.
• <filter-mapping>: 이 필터를 어떤 요청에 적용할지 설정합니다. url-pattern을 /*로 지정하여 이 애플리케이션에 들어오는 모든 요청에 대해 인코딩 필터가 동작하도록 합니다.

 

📝 더 나은 코드를 위한 제안: Java 기반 설정으로 전환

web.xml을 사용하는 XML 기반 설정은 전통적이고 직관적이지만, 최근에는 Java 클래스를 이용한 설정(Java-based Configuration)이 더 선호됩니다. XML 파일을 없애고 100% Java 코드로만 프로젝트를 관리할 수 있어 더 깔끔하고 타입-세이프(type-safe)한 장점이 있습니다.

web.xml의 내용을 다음과 같은 Java 클래스로 대체할 수 있습니다.

/src/main/java/com/example/config/MyWebAppInitializer.java (새 파일)

package com.example.config;

import org.springframework.web.filter.CharacterEncodingFilter;
import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;

import javax.servlet.Filter;

public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

    // Root-Context (root-context.xml)에 해당하는 설정 클래스를 지정합니다. (현재 프로젝트에는 없으므로 null)
    @Override
    protected Class<?>[] getRootConfigClasses() {
        return null;
    }

    // DispatcherServlet (servlet-context.xml)에 해당하는 설정 클래스를 지정합니다.
    @Override
    protected Class<?>[] getServletConfigClasses() {
        // dispatcher-servlet.xml을 대체할 Java 설정 클래스를 만들어야 합니다.
        // 예: return new Class<?>[] { WebConfig.class };
        return null; // 지금은 예시이므로 null로 둡니다.
    }

    // DispatcherServlet이 매핑될 경로를 지정합니다.
    @Override
    protected String[] getServletMappings() {
        return new String[]{"/"};
    }

    // 인코딩 필터 등 각종 필터를 설정합니다.
    @Override
    protected Filter[] getServletFilters() {
        CharacterEncodingFilter encodingFilter = new CharacterEncodingFilter();
        encodingFilter.setEncoding("UTF-8");
        encodingFilter.setForceEncoding(true);
        return new Filter[]{encodingFilter};
    }
}

주의: 위와 같이 Java 설정을 사용하려면 pom.xml에 spring-web 의존성을 추가하고, dispatcher-servlet.xml의 내용도 Java @Configuration 클래스로 옮겨야 합니다.

 

🎯 마무리

오늘은 Spring MVC 애플리케이션의 관문 역할을 하는 web.xml 파일에 대해 알아보았습니다.

요약:
    1.DispatcherServlet을 등록하여 모든 요청을 Spring 컨테이너로 연결합니다.
    2.CharacterEncodingFilter를 설정하여 안정적인 한글 처리를 보장합니다.

비록 Spring Boot의 등장으로 web.xml을 직접 작성하는 일이 줄었지만, 그 내부 동작 원리를 이해하는 것은 Spring MVC의 근간을 파악하는 데 매우 중요합니다. 이 글이 여러분의 Spring 학습에 도움이 되었기를 바랍니다