🚀 Spring Boot 2.7.x → 3.4.1 업그레이드 가이드 (1) 기본 업그레이드 준비 & 환경 설정

"Spring Boot 3.x로의 전환, 무엇을 준비해야 할까?"

Spring Boot 3.4.1로 업그레이드하면 Java 17+ 필수, Jakarta EE 전환, 라이브러리 변경, JPA(Hibernate) 업그레이드 등의 영향을 받습니다.
업그레이드를 진행하기 전에 반드시 아래 사항을 점검하고, 안정적인 마이그레이션을 위한 환경을 설정하세요!

 

📌 1. 단계별 업그레이드 전략

Spring Boot 3.x는 변경 사항이 많기 때문에, 바로 3.4.1로 업그레이드하는 대신 단계적으로 진행하는 것이 안정적입니다.

추천하는 업그레이드 순서

1️⃣ Spring Boot 2.7.x → 3.0.12 (기본적인 변경 사항 반영)
2️⃣ 3.0.12 → 3.2.6 (주요 라이브러리 마이그레이션)
3️⃣ 3.2.6 → 3.4.1 (최신 버전 적용 및 최적화)

🔹 Git 브랜치 전략

✅ feature/spring-boot-3-upgrade 브랜치를 생성하여 변경 사항을 안전하게 적용
✅ 업그레이드 과정 중 문제가 발생하면 git reset 또는 git revert로 롤백 가능

 

 

📌 2. 업그레이드 전에 확인해야 할 필수 사항

업그레이드를 하기 전에, 현재 프로젝트가 Spring Boot 3.x로 전환될 준비가 되어 있는지 점검해야 합니다.
아래 체크리스트를 확인하세요.

✅ [1] Java 17+ 사용 여부

• Spring Boot 3.x는 Java 17 이상에서만 동작합니다.
• Java 11 이하를 사용 중이라면 먼저 Java 17로 업그레이드하세요.

✅ [2] javax → jakarta 네임스페이스 변경

• 기존 javax 패키지가 Spring Boot 3.x부터 jakarta로 변경되었습니다.
• 예를 들어, javax.validation.constraints.NotNull은 이제 **jakarta.validation.constraints.NotNull**로 바뀌어야 합니다.
• ✅ 프로젝트 내에서 javax.가 사용된 부분을 검색하여 jakarta.로 변경하세요.

✅ [3] Spring Boot 3.x 지원 여부 확인 (spring-boot-properties-migrator 활용)
Spring Boot 3.x에서는 application.yml의 설정 키 값이 여러 개 변경되었습니다.
기존 설정이 Spring Boot 3.x에서도 정상 동작하는지 확인하려면 spring-boot-properties-migrator를 활용하세요.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <version>3.4.1</version>
    <scope>runtime</scope>
</dependency>

✅ 이 라이브러리를 실행하면, 변경이 필요한 설정 목록을 자동으로 찾아줍니다.
✅ 실행 후 logs/spring-boot-migrator.log 파일을 확인하여 수정해야 할 설정을 찾으세요.

 

---

📌 3. Gradle/Maven 빌드 설정 변경

업그레이드를 시작하기 전에 Gradle/Maven에서 Spring Boot 3.x 버전으로 변경해야 합니다.

✅ Gradle (build.gradle.kts)

plugins {
    id("org.springframework.boot") version "3.4.1"
    id("io.spring.dependency-management") version "1.1.4"
    kotlin("jvm") version "17"
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-security") // 최신 Spring Security
    implementation("org.springframework.boot:spring-boot-starter-data-jpa") // JPA 설정 추가
    runtimeOnly("org.postgresql:postgresql") // DB 설정
}

✅ spring-boot-gradle-plugin을 최신 버전(3.4.1)으로 변경하세요.
✅ kotlin("jvm") version "17"을 설정하여 Java 17 이상을 사용하도록 맞추세요.
✅ JPA 관련 변경 사항을 고려하여 spring-boot-starter-data-jpa 추가

 

✅ Maven (pom.xml)

<properties>
    <java.version>17</java.version>
    <spring.boot.version>3.4.1</spring.boot.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>${spring.boot.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies> 

✅ Java 17 이상을 사용하도록 java.version을 변경하세요.
✅ spring-boot.version을 3.4.1로 업데이트하세요.
✅ JPA 관련 의존성 추가 (spring-boot-starter-data-jpa, postgresql)

---

📌 4. JPA 관련 주요 변경 사항 (Hibernate 6.x 적용)

Spring Boot 3.x에서는 Hibernate가 5.x → 6.x로 업그레이드되면서, JPA 관련 주요 변경 사항이 있습니다.

🔹 1. hibernate.id.new_generator_mappings 기본값 변경

• 기존 Hibernate 5.x에서는 hibernate.id.new_generator_mappings = false가 기본이었으나,
• Hibernate 6.x에서는 기본값이 **true**로 변경됨.

✅ 해결 방법

기본적으로 설정을 유지할 경우, 기존 데이터베이스에서 자동 증가 키 생성 전략이 바뀔 가능성이 있음.
명시적으로 설정하는 것이 안전합니다.

spring:
  jpa:
    properties:
      hibernate:
        id:
          new_generator_mappings: false

 

🔹 2. @TableGenerator, @SequenceGenerator 변경

Hibernate 6.x에서는 기존 ID 전략을 jakarta.persistence 네임스페이스로 변경해야 합니다.

변경 전 (Hibernate 5.x, Spring Boot 2.x)

import javax.persistence.*;

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "user_seq")
    @SequenceGenerator(name = "user_seq", sequenceName = "user_sequence", allocationSize = 1)
    private Long id;

    private String name;
}

변경 후 (Hibernate 6.x, Spring Boot 3.x)

import jakarta.persistence.*;

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "user_seq")
    @SequenceGenerator(name = "user_seq", sequenceName = "user_sequence", allocationSize = 1)
    private Long id;

    private String name;
}

✅ javax.persistence → jakarta.persistence 변경 필요

 

🔹 3. Native Query 반환 타입 변경

Hibernate 6.x에서는 Native Query에서 DTO를 직접 매핑할 때,
기존의 @Query(nativeQuery = true) 방식이 동작하지 않을 수 있음.

변경 전 (Hibernate 5.x)

@Query(value = "SELECT id, name FROM users", nativeQuery = true)
List<UserDto> findAllUsers();

변경 후 (Hibernate 6.x)

@Query(value = "SELECT id, name FROM users", nativeQuery = true)
@SqlResultSetMapping(
    name = "UserDtoMapping",
    classes = @ConstructorResult(
        targetClass = UserDto.class,
        columns = {
            @ColumnResult(name = "id", type = Long.class),
            @ColumnResult(name = "name", type = String.class)
        }
    )
)
List<UserDto> findAllUsers();

✅ Native Query를 사용할 경우 @SqlResultSetMapping을 추가해야 함.

 

---

📌 5. 기존 라이브러리 호환성 점검

Spring Boot 3.x로 업그레이드하면 일부 라이브러리가 더 이상 지원되지 않거나, 새로운 버전이 필요할 수 있습니다.

🔹 주요 비호환 라이브러리 목록 및 대체 방법

기존 라이브러리 (Spring Boot 2.x)Spring Boot 3.x에서 대체 방법

springfox-swagger	springdoc-openapi (2.7.0 버전 추천)
javax.validation	jakarta.validation (spring-boot-starter-validation 포함됨)
org.springframework.boot.autoconfigure.EnableAutoConfiguration	@SpringBootApplication에 포함됨, 불필요
@WebSecurityConfigurerAdapter (Spring Security 5.x)	SecurityFilterChain으로 변경

✅ 프로젝트에서 위의 라이브러리를 사용하고 있다면, Spring Boot 3.x에서 동작하도록 업데이트하세요.

 

---