Spring Boot 버전업 (3.X.X) 의 변경 사항

개요

기존  Spring Boot 2.x 버전대에서 3.x 버전대로 업그레이드하는 경우

어떤 변경 사항이 있고 무엇을 수정해야 하는지 알아보자 

 

 

0. JAVA 17 로 변경 필수

 

1. Spring Security 선언 구조 변화 

• WebSecurityConfigurerAdapter 클래스 삭제
• 설정 방식 변경 ( 오버라이딩 방식에서 람다식으로 변경) 

// 기존 방식 
// 삭제
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .authorizeRequests()
            .antMatchers("/api/**").authenticated();
    }
}

 

// 신규 방식
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf.disable()) // 람다 DSL 필수
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/api/**").authenticated() // antMatchers -> requestMatchers 변경
        );
    return http.build();
}

 

2. javax -> jakarta 변경

• 기존에 사용하던 javax 패키지가 jakarta 패키지로 변경 
  • import javax.... => import jakarta.... 로 변경
• JPA(Hibernate), Validation, Servlet 등 엔터프라이즈 관련 패키지 모두 변경해줘야 함 
• QueryDSL의 경우 Spring boot에 부합하는 라이브러리를 추가 및 선언해줘 함 

// Boot 2.x
implementation 'com.querydsl:querydsl-jpa'
annotationProcessor 'com.querydsl:querydsl-apt:5.0.0:jpa' // 기존

// Boot 3.x
implementation 'com.querydsl:querydsl-jpa:5.0.0:jakarta' // :jakarta 필수
annotationProcessor "com.querydsl:querydsl-apt:5.0.0:jakarta"
annotationProcessor "jakarta.persistence:jakarta.persistence-api"
annotationProcessor "jakarta.annotation:jakarta.annotation-api"

 

 

3. Spring Data JPA findAll() 리턴값 변경

• 기존 Iterable<T> 반환  => 신규 List<T> 반환 

 

4. Controller 의 URL 매칭 엄격해짐 

• 기존 AntPathMatcher 에서 PathPatternParser로 변경 
• 기존 /users와 /users/ 동일한 것으로 인식 
• 신규 /users와 /users/ 다른 것으로 인식 
• 클라이언트 단에서 확인 및 변경 필요 

AntPathMatcher 와 PathPatternParser의 차이점 

AntPathMatcher

• 요청 올때마다 문자열 패턴 매칭 
• 상대적으로 느림(매 요청마다 연산)
• 와일드카드(**) 중간 사용 자유로움 

PathPatternParser

• 서버 로딩 시 패턴을 파싱 하여 트리 구조로 저장 
• 매우 빠름 
• 와일드키드(**) 제약 있음(주로 패턴의 끝에 사용 권장함)

 

5. Exception 발생 시 표준 스펙 응답 기본 제공 

• 기존 응답 객체를 꼭 만들어 줘야 함 
• 신규 기본 응답 리턴 

// yml 파일에 내용 추가 
spring:
  mvc:
    problem-details:
      enabled: true

// 기본 응답 예시
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Failed to convert 'id' with value 'abc'",
  "instance": "/api/users/abc"
}

 

// 커스텀 응답 예시 
@ExceptionHandler(UserNotFoundException.class)
public ProblemDetail handleUserNotFound(UserNotFoundException e) {
    // 1. 기본 스펙 생성 (status, message)
    ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(
        HttpStatus.NOT_FOUND, e.getMessage()
    );

    // 2. 표준 필드 커스텀
    problemDetail.setTitle("User Not Found");
    problemDetail.setType(URI.create("https://test/errors/user-not-found"));
    
    // 3. 비표준(커스텀) 필드 추가 (Map처럼 사용)
    problemDetail.setProperty("timestamp", Instant.now());
    problemDetail.setProperty("traceId", "abc-123-xyz"); // 로깅용 ID

    return problemDetail;
}

 

 

6. property.yml 의 키값 변경 

• 개발하는 동안 spring-boot-properties-migrator 의존성 추가하여 서버 실행하면 로그에서 표현해 줌