Spring Boot 버전별 정적 페이지 처리 차이

TIL: Spring Boot 버전별 정적 페이지 처리 차이 및 트러블 슈팅

오늘은 Spring Boot 버전 3.1.0과 3.3.4에서 정적 페이지를 컨트롤러를 통해 반환하는 방법의 차이를 발견하고 해결한 내용을 기록한다.

문제 상황

• 환경: Thymeleaf 의존성이 주석 처리된 상태에서 Spring Boot 프로젝트를 진행 중.
• hello.html 파일을 static 폴더에 저장하고, 컨트롤러에서 이를 반환하도록 아래와 같은 코드를 작성했다.

package com.sparta.springmvc.html;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HtmlController {

    @GetMapping("/static-hello")
    public String hello() {
        return "hello.html"; // 이 문자열에 부합하는 페이지를 찾아서 반환한다.
    }
}

• 3.1.0 버전: 정상적으로 http://localhost:8080/static-hello 경로로 접근하면 hello.html이 화면에 출력됨.
• 3.3.4 버전: 동일한 코드로 접근 시 500 에러가 발생함.

원인 분석

• Spring Boot 3.3.4 버전에서는 Thymeleaf 의존성이 없는 경우 뷰 리졸버(View Resolver) 설정이 더 엄격해져서 hello.html을 찾지 못하고 500 에러를 발생시킨 것으로 판단된다.
• 반면, 3.1.0 버전에서는 Thymeleaf 의존성이 없어도 어느 정도 유연하게 뷰를 처리해줬기 때문에 문제가 없었다.

해결 방법

1. Thymeleaf 의존성 추가: 가장 간단한 해결책은 Thymeleaf 의존성을 다시 추가하는 것.

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-thymeleaf</artifactId>
   </dependency>

   이 경우, 컨트롤러에서 반환되는 뷰 파일을 src/main/resources/templates 폴더에 위치시키고 return "hello";로 간단히 처리할 수 있다.

2. ViewResolver 직접 설정: Thymeleaf를 사용하지 않고도 컨트롤러를 통해 HTML 파일을 반환하려면, WebMvcConfigurer를 구현하여 ViewResolver를 직접 설정하는 방법이 있다.

   import org.springframework.context.annotation.Configuration;
   import org.springframework.web.servlet.config.annotation.ViewResolverRegistry;
   import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
   
   @Configuration
   public class WebConfig implements WebMvcConfigurer {
       @Override
       public void configureViewResolvers(ViewResolverRegistry registry) {
           registry.jsp("/static/", ".html");
       }
   }

   이렇게 하면 static 폴더에 있는 .html 파일을 컨트롤러에서 반환할 수 있다.

느낀 점

• Spring Boot 버전 업그레이드 시 기본 설정의 변화로 인해 기존에 정상 작동하던 코드가 오류를 발생할 수 있다는 점을 알게 되었다.
• 앞으로 버전 업그레이드 시 변경 사항을 주의 깊게 살펴보고 의존성을 적극적으로 활용하는 것이 중요하다는 것을 배웠다.

이를 통해 스프링 부트 버전별 동작 차이를 이해하고 해결할 수 있었으며, 의존성이나 설정의 중요성에 대해 다시 한번 깨닫게 되었다.