Spring Boot 3 마이그레이션 체크리스트 (2.x → 3.x)

소개

Spring Boot 3 마이그레이션은 단순한 버전 변경 이상이다. Java 버전, Spring Framework 6 적용, Jakarta 네임스페이스 전환 등 여러 축에서 수정이 필요하다. 이 문서는 처음 접하는 개발자도 따라 할 수 있도록 단계별 체크리스트와 예제 코드를 제공한다.

사전 준비

환경 요구사항

• Java 17 이상 사용 여부 확인
• 빌드 도구(Gradle/Maven) 최신 버전 준비
• 라이브러리 호환성 조사

레거시 코드 분석

• javax.* 패키지 사용 위치 파악
• 커스텀 리플렉션 또는 리소스 로딩 방식 점검
• 서드파티 라이브러리의 Spring 6/Boot 3 호환성 확인

주요 변경사항 요약

spring boot 3 변경사항 중 핵심은 Jakarta EE 네임스페이스 전환과 Spring Framework 6의 요구사항이다. spring boot 2 to 3 업그레이드 과정에서는 아래 항목을 우선 점검한다.

Java 요구사항

• Java 17 이상 필수
• 모듈 시스템 사용 시 추가 설정 검토

Jakarta 네임스페이스 전환

javax.* → jakarta.*로 패키지명이 변경되었다. JPA, Servlet, Validation 등에서 import 문을 전부 교체해야 할 수 있다.

// 변경 전
import javax.persistence.Entity;

// 변경 후
import jakarta.persistence.Entity;

Spring Framework 6 영향

• 기존 일부 API 제거 또는 수정
• 메시지 변환 및 검증 관련 동작 차이 확인

의존성 및 스타터 업데이트

Spring Boot 스타터 버전을 3.x로 변경하고, 호환되지 않는 서드파티 의존성은 교체 또는 업그레이드해야 한다.

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.1.0</version>
</parent>

점검 체크리스트

빌드 및 설정

• pom.xml 또는 build.gradle의 Spring Boot 버전 업데이트
• Gradle의 경우 toolchain 또는 compatibility 설정 확인
• 빌드 실패 시 로그에서 deprecated API 검사

코드 수정

• import javax → import jakarta로 전환
• 직렬화, 리플렉션 관련 코드가 Java 17에서 동작하는지 확인
• 애플리케이션 이벤트, 에러 핸들러 등 프레임워크 변경 영향 점검

구성 파일

application.properties/yml에서 제거된 프로퍼티 또는 이름이 바뀐 항목을 확인한다. Actuator 엔드포인트 이름 변경 등도 포함된다.

테스트

• 단위 테스트와 통합 테스트의 실행 여부 확인
• Spring Test 모듈 호환성 점검

런타임

• 컨테이너(서버)와의 호환성 확인
• 프로파일 환경별 설정 차이 점검

마이그레이션 절차(권장 순서)

• 1) 코드베이스 백업 및 버전 관리 분기 생성
• 2) Java 17로 컴파일 환경 변경 및 빌드 성공 확인
• 3) Spring Boot 버전만 3.x로 올리고 빌드/테스트 실행
• 4) javax → jakarta 변경 자동화 또는 수동 변환 수행
• 5) 서드파티 라이브러리 업그레이드 및 대체
• 6) 통합 테스트와 로컬 실행으로 기능 검증
• 7) 배포 전 스모크 테스트 및 모니터링 설정 확인

실제 예제: javax → jakarta 자동 변경

간단한 스크립트를 이용해 소스 내 import를 치환할 수 있다. 다음은 Unix sed 예시이다.

find src -name "*.java" -print0 | xargs -0 sed -i 's/import javax\./import jakarta./g'

문제 발생 시 점검 포인트

• 클래스패스 충돌(jakarta와 javax 혼용 여부)
• 서드파티 라이브러리의 내부 javax 사용 확인
• 테스트 환경과 운영 환경의 JDK 버전 불일치

마무리

spring boot 2 to 3 업그레이드는 준비와 검증이 핵심이다. 단계적으로 변경 사항을 적용하면 리스크를 줄일 수 있다. 이 체크리스트를 기반으로 빌드·코드·설정·테스트를 차례로 점검하면 마이그레이션 작업을 안정적으로 마무리할 수 있다.