🚨 Spring Boot 3.x 4.0 Migration: 실제로 무엇이 깨졌는가 (그리고 우리가 어떻게 고쳤는가)

Source: Dev.to

Jakarta 네임스페이스 문제

증상

Spring Boot 3.x로 Jakarta로 마이그레이션했더라도 일부 전이 의존성이 여전히 javax.* 클래스를 가져옵니다. 흔히 문제를 일으키는 항목은 다음과 같습니다:

• 오래된 검증 라이브러리
• SOAP / JAXB 도구
• 레거시 서블릿 필터

해결 방법

mvn dependency:tree | grep javax

그 다음:

• Jakarta‑호환 버전을 강제 적용합니다.
• 오래된 전이 의존성을 명시적으로 제외합니다.

Lesson: “It worked in 3.x” doesn’t mean it’s safe in 4.0. → 교훈: “3.x에서는 작동했었다”는 4.0에서도 안전하다는 뜻이 아닙니다.

Spring Security 구성 변경

증상

Spring Boot 4 시대의 Spring Security는 완전히 명시적인 구성을 기대합니다. 깨진 부분:

• 폐기된 DSL이 제거되었습니다.
• 기본값이 변경되었습니다(특히 CSRF 및 세션 처리).
• 사용자 정의 필터가 더 이상 자동 등록되지 않습니다.

해결 방법

명시적인 SecurityFilterChain 빈으로 전환하고 기본값에 의존하지 않도록 합니다.

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf.disable())
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated());
    return http.build();
}

Lesson: Implicit security configs are gone; be explicit or be surprised. → 교훈: 암시적인 보안 설정은 사라졌습니다; 명시적으로 작성하지 않으면 놀라게 됩니다.

스타터 이름 변경, 분할 및 제거

증상

여러 Spring Boot 스타터가 이름이 바뀌거나, 분할되거나, 완전히 제거되었습니다. 특히 다음 영역에서:

• 관측성
• Actuator 확장
• 레거시 통합

해결 방법

스타터를 수동으로 감사하십시오; 기존 목록을 신뢰하지 마세요.

mvn dependency:tree | grep spring-boot-starter

제거된 스타터를 다음으로 교체합니다:

• 명시적 라이브러리, 또는
• 새로운 모듈식 대안.

Java 베이스라인 불일치 (Java 21+)

증상

Spring Boot 4.0은 최신 Java(Java 21+) 사용을 더욱 강제합니다. 깨진 부분:

• Testcontainers 이미지
• ByteBuddy / Mockito 호환성
• JVM 플래그가 제거되었거나 무시됨

해결 방법

• 로컬 Java 버전, CI Java 버전, Maven 툴체인을 일치시킵니다.
• 테스트 라이브러리를 적극적으로 업그레이드합니다.

Lesson: Don’t debug Spring errors when it’s really a JVM mismatch. → 교훈: 실제 문제는 JVM 버전 불일치일 때 Spring 오류를 디버깅하지 마세요.

관측성 기본값 리팩터링

증상

Spring Boot 4는 관측성 기본값을 리팩터링했습니다:

• 엔드포인트가 기본적으로 비활성화됨
• 메트릭 이름이 변경됨
• 노출 규칙이 다름

해결 방법

Actuator 노출을 명시적으로 다시 선언합니다:

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics

Lesson: “No error” ≠ “working”. → 교훈: “오류 없음”이 곧 “정상 동작”을 의미하지는 않습니다.

마이그레이션 체크리스트 및 추가 읽을거리

우리는 모든 파괴적 변경, 해결책, 그리고 함정을 구조화된 마이그레이션 체크리스트에 문서화했습니다.

Full Spring Boot 3.x → 4.0 migration guide
🔗

포함 내용:

• 의존성 감사 단계
• 보안 마이그레이션 패턴
• 테스트 및 CI 수정
• Actuator 및 관측성 변경

우리는 실제 사례 기반 마이그레이션 가이드(마케팅 문서가 아님) 작은 디렉터리를 구축하고 있습니다:
🔗

Spring Boot 업그레이드, Java 버전 점프, 혹은 프레임워크 마이그레이션을 다루고 있다면, 거기서 유용한 정보를 찾을 수 있을 것입니다.

Spring Boot 업그레이드 중 가장 이상하게 깨진 것은 무엇이었나요?
조용히 동작이 바뀐 경우?
노트를 비교해 봅시다 👇