Spring Boot 3에서 4로 마이그레이션 — 실제로 깨지는 7가지와 해결

Spring Boot 3.5의 오픈소스 지원이 2026년 6월 30일 끝나면서 4.0으로 올려야 하나 고민하는 시점입니다. 미루면 보안 패치가 끊기고, 그냥 버전만 올리면 앱이 기동조차 안 되거나 API가 전부 403으로 막힙니다.

 

현업에서 Java·Spring을 다뤄온 관점에서 공식 마이그레이션 가이드를 실제 깨지는 항목 위주로 정리했습니다. 이 순서대로 가면 3.x에서 4.0까지 무엇이 깨지고 어떻게 고치는지 손에 잡힙니다.

왜 지금 올려야 하나 — 3.5 EOL

Spring Boot 3.5의 오픈소스 지원은 2026년 6월 30일 종료됐습니다. 이후 3.x 브랜치는 상용(Commercial) 계약이 있어야 보안 패치를 받습니다. 무료로 계속 쓰면 새 CVE가 나와도 패치가 안 옵니다.

 

그래서 판단은 단순합니다. 상용 지원을 결제할 계획이 없으면 4.0으로 올려야 합니다. 4.0은 Spring Framework 7과 Jakarta EE 11을 기반으로 하는 메이저 버전이라, 3.x에서 쓰던 코드가 그대로 굴러가지 않는 항목이 꽤 있습니다.

 

다만 무작정 올리는 건 비추입니다. Spring Boot 4 마이그레이션은 3.5.x를 브리지로 거쳐야 사고가 적습니다. 뒤 섹션에서 이유를 풀겠습니다.

올리기 전 준비 — Java·브리지·migrator

세 가지만 먼저 맞춰두면 절반은 끝납니다.

• Java 버전: 4.0의 최소 요구는 Java 17입니다. 21이나 25가 아니라 17이 하한선입니다. 가상 스레드 같은 최신 기능을 쓰려면 21/25가 권장되지만 필수는 아닙니다.
• 브리지 버전: 현재 3.2·3.3에 있다면 먼저 3.5.x로 올려 deprecation 경고를 확인합니다. 3에서 4로 바로 점프하면 뭐가 없어졌는지 한 번에 쏟아져서 원인 추적이 어렵습니다.
• 탐지 도구: spring-boot-properties-migrator를 의존성에 임시로 추가하면, 이름이 바뀌거나 사라진 프로퍼티를 기동 로그에 찍어줍니다. 정리 끝나면 이 의존성은 제거합니다.

Lombok·QueryDSL 같은 애노테이션 프로세서를 쓴다면 준비 단계에서 함께 버전을 점검하세요. 의존성 궁합은 Spring Boot Lombok 가이드에 정리해 뒀습니다.

실제로 깨지는 7가지

Spring Boot 4 마이그레이션에서 공식 가이드가 짚는, 업그레이드하면 실제로 걸리는 항목입니다. 표로 먼저 훑고, 실무에서 시간을 가장 많이 잡아먹는 Jackson 3과 403 두 개만 아래에서 풀어 설명합니다.

#	변경	증상	해결
1	Java 17 이상 필수 (21/25 권장)	UnsupportedClassVersionError	JDK 17+ 로 빌드
2	Jackson 3 group ID tools.jackson 이동	ClassNotFoundException·import 에러	import·의존성 group ID 교체
3	Spring Security 7 — authorizeRequests()·antMatchers() 제거	컴파일 에러	authorizeHttpRequests()·requestMatchers() 로 교체
4	REST API 403 — 업그레이드 후 stateless API 전면 차단	모든 API 403 Forbidden	stateless면 http.csrf(c -> c.disable()) 명시
5	Undertow 지원 제거	starter 없음·기동 실패	Tomcat/Jetty로 전환
6	deprecated API/프로퍼티 전량 제거	프로퍼티 무시·메서드 컴파일 에러	properties-migrator로 감지 후 수정
7	Jakarta EE 11 / Servlet 6.1 baseline	구버전 서블릿·플러그인 비호환	서블릿 컨테이너·빌드 플러그인 업

Jackson 3 — group ID가 바뀐다

4.0은 Jackson 3을 기본으로 씁니다. 여기서 함정은 일부 group ID가 com.fasterxml.jackson에서 tools.jackson으로 이동했다는 점입니다. 직접 Jackson 의존성을 명시했거나 커스텀 ObjectMapper를 쓰는 프로젝트는 import가 깨집니다.

 

주의할 예외가 있습니다. com.fasterxml.jackson.core와 com.fasterxml.jackson.annotation은 그대로 유지됩니다. 즉 @JsonProperty 같은 애노테이션 패키지는 안 바뀌고, ObjectMapper 본체 쪽 패키지가 이동합니다. 전부 일괄 치환하면 오히려 애노테이션이 깨지니, tools.jackson으로 옮겨야 하는 것과 유지되는 것을 구분해서 고쳐야 합니다.

업그레이드 후 API가 전부 403

가장 당황스러운 증상입니다. 빌드는 통과했는데 배포 후 모든 REST API가 403 Forbidden을 뱉습니다.

증상: 업그레이드 전엔 잘 되던 REST API가 4.0 배포 후 전부 403.

원인: Spring Security 7의 기본 설정 변화. JWT 등 stateless 토큰 API인데 CSRF 보호를 명시적으로 끄지 않으면 요청이 막힙니다.

해결: SecurityFilterChain에서 http.csrf(c -> c.disable())를 명시합니다.

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .csrf(c -> c.disable())                 // stateless JWT API면 명시
        .authorizeHttpRequests(auth -> auth     // authorizeRequests() 제거됨
            .requestMatchers("/api/public/**").permitAll()  // antMatchers() → requestMatchers()
            .anyRequest().authenticated());
    return http.build();
}

세션 기반 웹 앱이면 CSRF를 켜둔 채 토큰 처리를 맞추는 쪽이 맞습니다. stateless 토큰 API에 한해 disable하는 것이고, 세션 로그인까지 일괄로 끄라는 뜻은 아닙니다. Security 설정 전체 맥락은 Spring Boot API 응답 구조화와 같이 보면 감이 잡힙니다. Spring Boot 4 마이그레이션에서 이 403 한 줄을 놓치면 배포 직후 장애로 이어집니다.

실전 마이그레이션 순서

순서를 지키는 게 핵심입니다. 직점프하면 원인 추적이 배로 늘어납니다.

1. 3.5.x로 먼저 올린다 — 현재 버전에서 3.5로 이동. 여기서 기존 기능이 그대로 도는지 확인.
2. deprecation 경고를 전량 제거한다 — 로그에 뜨는 deprecated 항목을 하나씩 정리. properties-migrator로 프로퍼티도 점검.
3. 의존성·Java 버전을 교체한다 — Java 17+ 확인, Jackson 3(tools.jackson), 빌드 플러그인 버전 업.
4. 코드를 수정한다 — Security 7(authorizeHttpRequests·requestMatchers), Undertow를 쓰고 있었다면 Tomcat/Jetty로 전환.
5. 빌드·403 검증 후 배포한다 — 컴파일 통과 후 API가 403 안 뱉는지 로컬에서 확인하고 배포.

솔직히 3에서 4로 직점프는 비추입니다. 3.5가 사실상 브리지 역할을 해서, 2단계에서 경고를 0으로 만들어 두면 4.0 전환 때 새로 터지는 건 Jackson·Security·서블릿 정도로 좁혀집니다.

함정 + Q&A

• deprecated "개수"를 세지 마세요. 3.x에서 deprecated였던 API·프로퍼티는 4.0에서 전량 사라집니다. 몇 개가 사라졌다고 외울 게 아니라, properties-migrator가 로그로 알려주는 항목만 고치면 됩니다.
• Undertow 사용자는 준비 단계에서 미리 전환하세요. 4.0에서 Undertow starter가 사라져서, 서버 전환을 안 해두면 기동 자체가 안 됩니다.
• 빌드 플러그인 버전도 확인하세요. Jakarta EE 11 / Servlet 6.1 baseline과 맞지 않는 구버전 플러그인은 비호환입니다.

Spring Boot 4 마이그레이션은 이 세 함정만 미리 걸러내도 배포 당일에 당황할 일이 크게 줄어듭니다.

Q&A — 자주 보는 질문 5개

Q. 3.x를 계속 써도 되나요?
A. 3.5의 오픈소스 지원은 2026년 6월 30일 종료됐습니다. 이후 3.x는 상용 계약이 있어야 보안 패치를 받습니다. 무료로 보안 패치가 필요하면 4.0으로 올려야 합니다.

Q. 언제 올리는 게 맞나요?
A. 곧바로 4.0으로 가지 말고, 먼저 3.5.x로 올려 deprecation 경고를 0으로 만든 뒤 4.0으로 가세요. 직점프는 원인 추적이 어려워 비추입니다.

Q. Java는 몇 버전이 필요한가요?
A. 최소 Java 17입니다. 21이나 25는 권장이지 필수는 아닙니다. 가상 스레드 같은 최신 기능이 필요하면 21/25를 고르면 됩니다.

Q. Jackson 컴파일 에러가 나요.
A. 4.0은 Jackson 3을 기본으로 쓰고, group ID가 tools.jackson으로 이동했습니다. import와 의존성 group ID를 교체하세요. 단 com.fasterxml.jackson.core와 .annotation은 그대로 유지되니 전부 일괄 치환하면 안 됩니다.

Q. 업그레이드 후 API가 전부 403이에요.
A. Spring Security 7의 기본 설정 변화 때문입니다. JWT 등 stateless 토큰 API면 http.csrf(c -> c.disable())를 명시하세요. 세션 기반 앱이면 CSRF를 켠 채로 맞추는 게 맞습니다.

같은 환경이면 위 순서대로 따라가도 무리 없습니다.

📎 이 카테고리의 다른 글

• .NET 8.0에서 .NET 9.0으로의 전환: 주요 변화와 성능 이점 — 2026-03-14
• Spring Boot에서 API 응답을 구조화하는 가장 좋은 방법 — 2024-11-23
• Spring Boot에서 Lombok을 활용한 효율적인 Java 개발 가이드 — 2024-12-02

같은 개발 정보 & 최신 동향 카테고리에서 이어서 읽기

설치 환경: JDK 21, Gradle 8.x, Spring Boot 4.0