[트러블슈팅] Spring Boot 4.x 업그레이드 시 Jackson 패키지 변경 주의하기

상황

Spring Boot 4.x 환경에서 ObjectMapper를 사용하는 코드를 작성하다가 컴파일 오류가 발생했다. Spring Boot 4.x는 Jackson 3.x를 사용하는데, Jackson 3.x에서 패키지 구조와 예외 계층이 변경됐기 때문이다.

변경된 패키지

	Jackson 2.x (Boot 3.x)	Jackson 3.x (Boot 4.x)
ObjectMapper	com.fasterxml.jackson.databind.ObjectMapper	tools.jackson.databind.ObjectMapper
JsonProcessingException	com.fasterxml.jackson.core.JsonProcessingException	tools.jackson.core.JacksonException
어노테이션	com.fasterxml.jackson.annotation.*	동일 (변경 없음)

어노테이션은 기존 패키지를 그대로 유지하므로 @JsonPropertyOrder 같은 어노테이션은 수정하지 않아도 된다.

예외 계층 변경

• Jackson 2.x에서 JsonProcessingException은 IOException을 상속하는 checked 예외였다. 따라서 try-catch 또는 throws 선언이 필수였다.
• Jackson 3.x에서 JacksonException은 RuntimeException을 상속하는 unchecked 예외로 변경됐다. try-catch가 선택적이지만, 직렬화/역직렬화 실패를 로깅하거나 예외 처리가 필요한 경우 여전히 사용할 수 있다.

// Jackson 2.x — checked 예외이므로 try-catch 필수
try {
    objectMapper.writeValueAsString(data);
} catch (JsonProcessingException e) { ... }

// Jackson 3.x — unchecked 예외이므로 try-catch 선택적
try {
    objectMapper.writeValueAsString(data);
} catch (JacksonException e) { ... }

해결 방법

import 경로를 Jackson 3.x 기준으로 변경한다.

// 변경 전 (Jackson 2.x)
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

// 변경 후 (Jackson 3.x)
import tools.jackson.core.JacksonException;
import tools.jackson.databind.ObjectMapper;

// 어노테이션은 그대로 유지
import com.fasterxml.jackson.annotation.JsonPropertyOrder;

인사이트

Spring Boot 버전을 올릴 때는 단순히 의존성 버전만 바꾸는 게 아니라, 함께 업그레이드되는 서드파티 라이브러리의 breaking change도 반드시 확인해야 한다. 특히 Jackson처럼 광범위하게 사용되는 라이브러리는 패키지 경로나 예외 계층 변경이 프로젝트 전반에 걸쳐 컴파일 오류를 유발할 수 있다.