Spring Boot 4.1 마이그레이션, 3.x 지원 종료 뒤 실제로 깨지는 곳

Spring Boot 4.1 이야기를 꺼내면 “3.x로도 잘 돌아가는데 왜 지금?”이라는 반응이 먼저 나옵니다. 이유는 기술이 아니라 달력에 있습니다. Spring Boot 3.5의 오픈소스 지원은 2026년 6월 30일에 끝났고, 4.0도 2026년 12월 31일 종료가 예정돼 있습니다. 공공·금융 프로젝트처럼 보안 패치 적용 여부가 감사 항목인 곳이라면, 남은 선택지는 4.1로 올리거나 유료 연장 지원을 사는 것입니다.

저는 Java와 Spring으로 엔터프라이즈 시스템을 20년 넘게 만들어 오면서 메이저 업그레이드를 여러 번 겪었습니다. 매번 같은 교훈을 얻습니다. 업그레이드 작업의 대부분은 버전 숫자를 바꾸는 일이 아니라 지금까지 암묵적으로 기대던 기본값을 찾아내는 일입니다. 이 글은 새 기능 소개보다, 4.1로 올릴 때 실제로 깨지는 곳과 그것을 운영 전에 잡아내는 방법을 정리합니다.

일정과 기준선

버전 출시 OSS 지원 종료 비고
3.4 – 2025-12-31 마지막 패치 3.4.13
3.5 – 2026-06-30 마지막 패치 3.5.16
4.0 2025-11-20 2026-12-31 Spring Framework 7, Jakarta EE 11
4.1 2026-06-10 2027년 중반(추정) gRPC 자동 구성, SSRF 완화
4.2 2026-11 예정 – 반기 출시 주기

최소 Java 버전은 3.x와 같은 17입니다. 지원 범위는 4.0이 Java 17~25, 4.1이 17~26으로 알려져 있고, 4.1에서 jOOQ 3.20 지원을 쓰려면 Java 21이 필요합니다. 기준선은 Jakarta EE 11, Servlet 6.1입니다. 3.x에서 이미 jakarta 패키지로 옮겼다면 패키지명 재작성은 필요 없습니다. 지원 종료일은 spring.io 공식 지원 표로 한 번 더 확인하시기 바랍니다.

반기 출시 주기라는 점도 계획에 넣어야 합니다. 마이너 버전 하나의 OSS 지원 기간이 대략 1년 남짓이므로, 앞으로는 ‘몇 년에 한 번 큰 업그레이드’가 아니라 ‘반년마다 작은 업그레이드’를 감당할 수 있는 파이프라인이 필요합니다.

가장 먼저 깨지는 세 곳

1. 자동 구성 모듈 분리

4.0에서 자동 구성이 기능별 모듈로 나뉘었습니다. 업그레이드 직후 “빈을 찾을 수 없다(No qualifying bean)”는 오류가 나면 대부분 여기서 시작합니다. 예전에는 starter 하나로 딸려 오던 자동 구성이 이제는 해당 모듈을 명시해야 붙는 경우가 있습니다. 해결 순서는 단순합니다. 실패한 빈의 자동 구성 클래스를 찾고, 그 클래스가 들어 있는 모듈을 의존성에 추가합니다.

더 확실한 방법은 업그레이드 전후의 자동 구성 결과를 비교하는 것입니다. 3.5 환경에서 조건 평가 보고서를 남겨 두고, 4.0에서 같은 보고서를 뽑아 차이를 봅니다.

# 업그레이드 전후 각각 실행해 매칭된 자동 구성 목록을 비교
java -jar app.jar --debug 2>&1 | sed -n '/Positive matches/,/Negative matches/p' > conditions-3.5.txt
java -jar app.jar --debug 2>&1 | sed -n '/Positive matches/,/Negative matches/p' > conditions-4.0.txt
diff <(grep -o '^   [A-Za-z]*AutoConfiguration' conditions-3.5.txt | sort) \
     <(grep -o '^   [A-Za-z]*AutoConfiguration' conditions-4.0.txt | sort)

빠진 자동 구성이 목록으로 나오므로, 기동 오류를 하나씩 따라가는 것보다 훨씬 빠릅니다. 기동은 되지만 기능이 조용히 빠진 경우(예: 메트릭 수집, 캐시 설정)도 이 비교에서 드러납니다.

2. Jackson 3

Jackson 3은 패키지가 com.fasterxml.jackson에서 tools.jackson으로 바뀌었고, 날짜는 기본적으로 ISO-8601 문자열로 직렬화되며, 예외가 unchecked로 바뀌었습니다.

// before (Jackson 2)
import com.fasterxml.jackson.databind.ObjectMapper;

// after (Jackson 3)
import tools.jackson.databind.json.JsonMapper;

패키지 변경은 컴파일러가 잡아 줍니다. 위험한 것은 날짜 기본값처럼 컴파일 오류 없이 API 응답만 바뀌는 변경입니다. 숫자 타임스탬프를 기대하던 모바일 앱이나 대외 기관 연동이 업그레이드 다음 날 깨집니다. 이를 막는 가장 싼 방법은 업그레이드 전에 응답 스냅샷 테스트를 만들어 두는 것입니다.

@SpringBootTest
@AutoConfigureMockMvc
class ApiContractSnapshotTest {
    @Autowired MockMvc mvc;

    @ParameterizedTest
    @ValueSource(strings = {"/api/orders/1001", "/api/members/me", "/api/settlements?month=2026-09"})
    void responseMatchesSnapshot(String uri) throws Exception {
        String body = mvc.perform(get(uri).with(user("tester")))
                         .andReturn().getResponse().getContentAsString();
        Path snap = Path.of("src/test/resources/snapshots", uri.replaceAll("[^a-zA-Z0-9]", "_") + ".json");
        if (Files.notExists(snap)) { Files.writeString(snap, body); return; }   // 3.5에서 최초 생성
        JSONAssert.assertEquals(Files.readString(snap), body, JSONCompareMode.STRICT);
    }
}

3.5에서 한 번 돌려 스냅숏을 만들고, 4.x에서 같은 테스트를 돌리면 날짜 형식, null 필드 포함 여부, 숫자 표현 차이가 실패로 드러납니다. 차이를 확인한 뒤 의도대로 기존 형식을 유지할지, 새 기본값을 받아들이고 소비자에게 공지할지를 결정합니다. 커스텀 직렬화기와 ObjectMapper 설정이 여러 곳에 흩어져 있다면, 이번 기회에 한 설정 클래스로 모으는 것을 권합니다.

3. 빌드 옵션과 제거된 API

  • 4.1은 4.0에서 폐기 예정으로 표시된 API를 모두 제거했습니다. 3.5 → 4.0 → 4.1 순서로 가며 경고를 정리하는 이유입니다.
  • 컨테이너 이미지 빌드에 쓰던 layertools JAR 모드는 사라지고 tools 모드를 써야 합니다. Dockerfile의 계층 추출 단계가 깨집니다.
  • Maven에서 테스트 AOT 처리까지 건너뛰려면 -DskipTests가 아니라 -Dmaven.test.skip=true를 써야 합니다. 업그레이드 후 CI 시간이 갑자기 늘었다면 이것부터 확인합니다.
  • 4.1에서 Apache Derby 지원, Dynatrace V1 속성, DevTools LiveReload가 새로 폐기 예정이 됐습니다.

4.1에서 얻는 것

기능 내용 실무 의미
gRPC 자동 구성 서버·클라이언트 자동 구성, Netty 단독과 Servlet HTTP/2 전송, @GrpcAdvice 사내 MSA에서 별도 스타터 없이 gRPC 도입
SSRF 완화 InetAddressFilter로 HTTP 클라이언트 대상 주소 대역을 허용·차단 목록으로 제한 사용자 입력 URL 호출 기능의 기본 방어선
API 버저닝 Spring Framework 7의 매핑 수준 버전 지정 v1/v2 컨트롤러 복제 대신 한 컨트롤러에서 분기
HTTP 서비스 클라이언트 @ImportHttpServices 선언형 설정 클라이언트 설정 보일러플레이트 제거
JSpecify @NullMarked, @Nullable Kotlin·정적 분석 도구와 null 계약 공유

저는 이 중 SSRF 완화를 가장 중요하게 봅니다. LLM 에이전트가 사내 API를 도구로 호출하는 구조가 늘면서, 모델이 만든 URL을 서버가 대신 호출하는 경로가 곳곳에 생겼습니다. 웹훅, 링크 미리보기, 문서 수집기, 에이전트의 HTTP 도구가 모두 그렇습니다. 프롬프트 인젝션으로 모델이 클라우드 메타데이터 엔드포인트나 내부 관리 콘솔 주소를 만들어 내면 서버가 그 요청을 대신 보냅니다. 네트워크 방화벽만으로 막으려 하면 내부망 안의 서비스 간 호출은 걸러지지 않습니다. 애플리케이션 계층에서 사설 대역, 루프백, 링크 로컬 주소를 기본 차단하고 필요한 대상만 허용하면 방어가 한 겹 더 생깁니다. 이때 DNS 재바인딩(검증 시점과 연결 시점의 IP가 다른 공격)까지 막으려면 이름이 아니라 실제 연결 IP로 검사하는지 확인해야 합니다.

단계별 순서

  1. 3.5 최신 패치로 올리고 폐기 경고를 0으로. 이것이 출발점입니다.
  2. 안전망 만들기. 위의 응답 스냅샷 테스트와 자동 구성 비교 보고서를 3.5에서 만들어 둡니다.
  3. Java 버전 결정. 17로도 되지만 운영 JDK를 21 이상 LTS로 맞추면 일부 기능 제약이 없어집니다. JDK 교체와 Spring 업그레이드를 같은 배포에 섞지 않습니다.
  4. 4.0 전환. 자동 구성 누락을 해결하고 기동 테스트·슬라이스 테스트를 통과시킵니다. OpenRewrite 같은 자동 리팩터링 도구의 Spring Boot 업그레이드 레시피를 쓰면 기계적인 변경을 줄일 수 있지만, 결과는 반드시 리뷰합니다.
  5. Jackson 3 전환을 별도 작업으로. 스냅샷 차이를 하나씩 결정합니다.
  6. 4.1 전환과 빌드 정리. layertools, skipTests 관련 CI 설정을 고칩니다.
  7. 새 기능은 마지막에, 별도 배포로. SSRF 필터, gRPC, API 버저닝은 업그레이드가 안정된 뒤 켭니다.

여러 서비스를 가진 조직의 일정

서비스가 여러 개인 조직에서 한꺼번에 올리면 원인 추적이 어려워집니다. 공통 라이브러리를 먼저 올리고, 트래픽이 적고 테스트가 잘 갖춰진 서비스를 첫 대상으로 고릅니다. 첫 서비스에서 나온 오류와 해결 방법을 위키에 정리해 두면, 다음 서비스부터는 같은 문제를 반나절 안에 넘길 수 있습니다. 일정은 보통 공통 모듈 정리 1주, 시범 서비스 1~2주, 나머지 순차 전환으로 나누고, 운영 배포는 서비스마다 따로 잡아 한 번에 두 개 이상 올리지 않습니다. 성능은 기동 시간, 메모리 사용량, 주요 API 응답 시간 세 가지만 전후로 기록해도 충분합니다.

업그레이드를 기능 개발과 같은 스프린트에 섞지 않는 것도 중요합니다. 섞으면 버그가 업그레이드 때문인지 새 기능 때문인지 구분하기 어렵고, 결국 롤백 판단이 늦어집니다.

올리지 않는 것이 맞을 때

2026년 안에 종료 예정인 레거시 시스템이거나, 핵심 라이브러리 하나가 Spring Framework 7을 지원하지 않는다면 무리해서 올리지 않는 편이 낫습니다. 이때는 유료 연장 지원이나 보안 패치 백포트 계획을 세우고, 전환 대상에서 뺀 결정과 그 이유를 문서로 남깁니다. 감사에서 문제가 되는 것은 ‘구버전 사용’이 아니라 ‘위험을 알고도 관리 계획이 없는 상태’입니다.

맺으며

Spring Boot 4.1 전환은 지원 종료 일정 때문에 미룰 수 없는 작업이 됐습니다. 자동 구성 분리, Jackson 3, 빌드 옵션 변화를 단계별로 나누고, 업그레이드 전에 응답 스냅숏과 자동 구성 비교라는 안전망을 먼저 깔아 두면 위험은 생각보다 작습니다. 그 대가로 SSRF 완화와 gRPC 자동 구성처럼, 특히 AI 에이전트가 사내 시스템을 호출하는 시대에 바로 쓸 수 있는 기능을 얻습니다.

참고 자료

댓글 남기기