[멀티캠퍼스] 풀스택 개발자 아카데미 (26) - Spring Boot(2)

1. 시작하며: XML 없는 세상에서의 웹 개발

지난 글에서는 스프링 부트의 등장 배경과 핵심 철학인 자동 설정(Auto-Configuration) 에 대해 알아보았다. 복잡한 pom.xml 의존성 관리를 스타터(Starter)로 해결하고, 내장 톰캣을 이용해 간편하게 서버를 실행하는 경험은 그야말로 신선한 충격이었다.

하지만 "XML 설정 파일을 쓰지 않는다"는 것은 개발자에게 새로운 과제를 안겨준다. "그럼 web.xml에 등록하던 필터(Filter)는 어디에 설정하지?", "정적 파일(CSS, 이미지) 경로는 어떻게 바꾸지?", "MyBatis 설정은 어디서 해?"와 같은 의문이 생기기 마련이다.

이번 글에서는 이러한 궁금증을 해결하고, 진정한 '스프링 부트 스타일' 의 웹 애플리케이션을 구성하는 방법을 다룬다. web.xml 없이 자바 코드로 웹 설정을 다루는 WebConfig 클래스의 활용법, application.properties를 이용한 초간단 MyBatis 연동, 그리고 @MapperScan을 이용한 매퍼 자동 등록까지, 실무에서 반드시 사용되는 핵심 설정 패턴들을 파헤쳐 보자.

2. Java Config

레거시 스프링에서는 web.xml이 웹 애플리케이션의 대문 역할을 했다. DispatcherServlet을 등록하고, 한글 처리를 위한 CharacterEncodingFilter를 등록하는 등 모든 초기 설정이 이곳에서 이루어졌다 .

스프링 부트에서는 web.xml이 없다. 대신 대부분의 필수 설정(인코딩 필터, 뷰 리졸버 등)을 자동 설정이 처리해준다. 하지만 개발자가 직접 세밀한 제어를 해야 할 때는 자바 설정(Java Config) 방식을 사용한다.

2.1. 필터(Filter) 설정: application.properties vs 자바 빈

가장 흔한 예인 'UTF-8 인코딩 필터'를 보자. 레거시에서는 web.xml에 수십 줄의 XML 코드를 작성해야 했지만 , 스프링 부트에서는 application.properties에 다음 한 줄을 작성하는 것으로 충분하다(심지어 최신 버전은 기본값이라 생략 가능하다).

# application.properties
server.servlet.encoding.charset=UTF-8
server.servlet.encoding.force=true

만약 개발자가 직접 만든 커스텀 필터를 등록해야 한다면 어떻게 할까? web.xml의 <filter> 태그 대신, 해당 필터 클래스를 스프링 빈(Bean) 으로 등록하거나 FilterRegistrationBean을 사용하면 된다.

// 커스텀 필터 등록 예시 (Java Config)
@Configuration
public class FilterConfig {
    @Bean
    public FilterRegistrationBean<MyCustomFilter> loggingFilter() {
        FilterRegistrationBean<MyCustomFilter> registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new MyCustomFilter());
        registrationBean.addUrlPatterns("/api/*"); // 필터 적용 경로 설정
        return registrationBean;
    }
}

3. WebMvcConfigurer와 정적 자원의 관리

웹 애플리케이션은 HTML뿐만 아니라 이미지, CSS, JavaScript 파일과 같은 정적 자원(Static Resources)을 제공해야 한다.

3.1. 기본 정적 자원 경로

스프링 부트는 기본적으로 다음 경로들을 정적 자원 루트로 인식한다 . 별도의 설정 없이 이 폴더에 파일을 넣으면 브라우저에서 접근할 수 있다.

• classpath:/static
• classpath:/public
• classpath:/resources
• classpath:/META-INF/resources

예를 들어, src/main/resources/static/images/logo.png에 파일을 두면, http://localhost:8080/images/logo.png로 접근 가능하다.

3.2. WebConfig로 외부 경로 매핑하기

하지만 파일 업로드 기능 등을 구현할 때, 업로드된 파일을 프로젝트 내부(src 폴더)가 아닌 로컬 디스크의 특정 폴더(예: C:/uploads/) 에 저장하고 불러와야 할 때가 있다. 레거시 스프링에서는 servlet-context.xml에 <resources mapping="..." location="..." /> 태그를 사용했었다.

스프링 부트에서는 WebMvcConfigurer 인터페이스를 구현한 설정 클래스(WebConfig)를 통해 이를 처리한다.

WebConfig.java 작성:

package com.example.boot.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration // 스프링 설정 클래스임을 명시
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 브라우저에서 /images/** 로 요청이 오면
        // 로컬 디스크의 C:/spring_uploads/ 폴더에서 파일을 찾는다.
        registry.addResourceHandler("/images/**")
                .addResourceLocations("file:///C:/spring_uploads/");
    }
}

이 설정을 통해 사용자가 업로드한 파일을 서버 재시작 없이 즉시 웹에서 접근할 수 있게 된다. file:/// 접두어를 사용하여 로컬 파일 시스템을 가리키는 것이 핵심이다.

4. MyBatis 연동의 진화

레거시 프로젝트에서 MyBatis를 연동하려면 root-context.xml에 DataSource, SqlSessionFactoryBean, SqlSessionTemplate 등을 일일이 빈으로 등록해야 했다 . 코드가 길고 오타가 발생하기 쉬웠다. 스프링 부트는 이를 application.properties 설정 몇 줄로 끝낸다.

4.1. application.properties 설정

mybatis-spring-boot-starter 의존성이 추가되어 있다면, 스프링 부트는 설정 파일의 정보를 읽어 DataSource와 SqlSessionFactory를 자동으로 생성한다.

# 1. DB 연결 정보 (HikariCP 자동 구성)
spring.datasource.driver-class-name=oracle.jdbc.OracleDriver
spring.datasource.url=jdbc:oracle:thin:@//your_db_url:1521/XEPDB1
spring.datasource.username=your_db_username
spring.datasource.password=your_db_password

# 2. MyBatis 설정
# Mapper XML 파일의 위치 지정 (매우 중요!)
mybatis.mapper-locations=classpath:mappers/*.xml
# VO(DTO) 패키지 별칭 지정 (XML에서 패키지명 생략 가능)
mybatis.type-aliases-package=com.example.boot.dto
# SQL 실행 로그 출력 (디버깅용)
logging.level.com.example.boot.mapper=DEBUG

단 7~8줄의 설정으로 복잡했던 XML 설정을 대체했다. mybatis.mapper-locations는 SQL이 작성된 XML 파일이 어디에 있는지 알려주는 가장 중요한 설정이다.

4.2. @MapperScan: 매퍼 인터페이스 자동 스캔

XML 설정 시절에는 <mybatis-spring:scan> 태그를 사용해 매퍼 인터페이스를 스캔했다. 스프링 부트에서는 메인 애플리케이션 클래스나 설정 클래스에 @MapperScan 어노테이션을 붙여 해결한다 .

package com.example.boot;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("com.example.boot.mapper") // Mapper 인터페이스가 위치한 패키지 경로
public class MyBootAppApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyBootAppApplication.class, args);
    }
}

이 어노테이션을 붙이면 해당 패키지 아래의 인터페이스들을 자동으로 찾아 구현체를 만들고 스프링 빈으로 등록해준다. 이제 서비스(Service) 계층에서 @Autowired로 매퍼를 주입받아 바로 사용할 수 있다.

5. 실습: 상품 관리 시스템 (Boot Version)

이제 배운 내용을 종합하여 간단한 상품 목록 조회 기능을 스프링 부트 스타일로 구현해보자. (JSP 사용 설정은 지난 글을 참고한다.)

1. 프로젝트 구조

IntelliJ IDEA의 프로젝트 뷰는 다음과 같은 구조를 가진다. XML 설정 파일이 사라지고 자바 파일과 properties 파일만 남은 것을 확인할 수 있다.

src/
└── main/
    ├── java/
    │   └── com.example.boot
    │       ├── config
    │       │   └── WebConfig.java           :정적 리소스 설정
    │       ├── controller
    │       │   └── ProductController.java   :웹 요청 처리
    │       ├── dto
    │       │   └── ProductDTO.java          :데이터 모델 (Lombok 사용)
    │       ├── mapper
    │       │   └── ProductMapper.java       :DB 접근 인터페이스
    │       └── service
    │           └── ProductService.java      :비즈니스 로직
    └── resources/
        ├── mappers/
        │   └── ProductMapper.xml            :SQL 쿼리
        └── application.properties           :설정 파일

2. DTO 작성

package com.example.boot.dto;

import lombok.Data;

@Data // Getter, Setter, ToString 등을 한 번에 생성
public class ProductDTO {
    private String prdNo;
    private String prdName;
    private int prdPrice;
    private String prdCompany;
    // ... 기타 필드
}

3. Mapper 인터페이스 및 XML

// ProductMapper.java
package com.example.boot.mapper;

import com.example.boot.dto.ProductDTO;
import java.util.List;

public interface ProductMapper {
    List<ProductDTO> selectAllProducts();
}

<mapper namespace="com.example.boot.mapper.ProductMapper">
    <select id="selectAllProducts" resultType="ProductDTO">
        SELECT * FROM product ORDER BY prdNo ASC
    </select>
</mapper>

(application.properties에서 type-aliases-package를 설정했으므로 resultType에 패키지명을 생략하고 ProductDTO만 쓸 수 있다.)

4. Controller 작성

@Controller
public class ProductController {

    @Autowired
    private ProductService productService; // Service 주입

    @GetMapping("/products")
    public String list(Model model) {
        List<ProductDTO> list = productService.getAllProducts();
        model.addAttribute("productList", list);
        return "productList"; // /WEB-INF/views/productList.jsp
    }
}

5. 실행 및 결과

애플리케이션을 실행(Run)하고 브라우저에서 http://localhost:8080/products에 접속하면, DB에서 조회된 상품 목록이 JSP를 통해 렌더링된다. web.xml이나 root-context.xml 없이도 완벽하게 동작한다.

6. 마무리하며: 설정의 다이어트, 개발의 가속화

이번 글에서는 스프링 부트가 제공하는 간결한 설정 방식을 통해 MVC 패턴을 구현하고 정적 자원을 관리하는 방법을 알아보았다.

• web.xml의 복잡한 필터 설정은 **application.properties**나 자바 빈 설정으로 대체되었다.
• servlet-context.xml의 정적 자원 매핑은 **WebMvcConfigurer**와 WebConfig 클래스로 깔끔하게 정리되었다.
• MyBatis 연동은 application.properties와 **@MapperScan**을 통해 XML 설정 파일 없이도 즉시 사용 가능해졌다.

이처럼 스프링 부트는 "설정보다는 관례(Convention over Configuration)"를 따르며 개발자가 설정 파일과 씨름하는 시간을 획기적으로 줄여준다. 이제 우리는 인프라 구축에 대한 걱정을 덜고, 비즈니스 로직이라는 본질에 더욱 집중할 수 있게 되었다.

다음 글에서는 웹 애플리케이션의 필수 기능인 파일 업로드 기능과, 모바일 및 프론트엔드 프레임워크(Vue, React)와 통신하기 위한 REST API를 스프링 부트 환경에서 구현하는 방법을 다룰 것이다. 특히 파일 업로드 시 발생하는 예외 처리와 비동기(Ajax) 방식으로 파일을 업로드하는 기법을 상세히 알아볼 예정이다.

7. 평가

이번 글은 레거시 스프링과 스프링 부트의 설정 방식 차이를 명확히 대비시키며, 스프링 부트의 편리함을 강조하는 데 초점을 맞췄다. 특히 WebMvcConfigurer를 이용한 정적 자원 관리는 파일 업로드 기능 구현 시 필수적인 내용이므로 별도의 단원으로 다루어 이해를 도왔다.

MyBatis 연동 또한 실무에서 가장 많이 쓰이는 패턴인 application.properties + @MapperScan 조합을 제시하여 바로 적용 가능하도록 했다. 전체적으로 코드는 간결해졌지만, 그 이면에서 스프링 부트가 얼마나 많은 일을 자동으로 처리해주고 있는지 이해하는 것이 중요하다.