B컷전문 | 개발과 인생의 이야기

Jackson과 Spring Boot에서 JSON 처리 중 자주 발생하는 에러 메시지와 그 원인을 분석합니다. 실전 환경에서 발생하는 문제 해결 전략을 중심으로 직렬화/역직렬화 오류에 대응합니다.

---

1. UnrecognizedPropertyException: 알 수 없는 필드 오류

증상

com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException:
Unrecognized field "unknown_field"

원인

JSON 요청 본문에 Java 클래스에 정의되지 않은 필드가 포함된 경우 발생

해결 방법

1. DTO 클래스에 해당 필드를 추가하거나
2. 다음 설정을 통해 무시할 수 있음

// 클래스 단위 설정
@JsonIgnoreProperties(ignoreUnknown = true)
public class User { ... }

// 또는 ObjectMapper 전역 설정
mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

---

2. InvalidFormatException: 형식 불일치 오류

증상

Cannot deserialize value of type `int` from String "abc"

원인

JSON 문자열의 값이 Java 타입과 일치하지 않음 (예: 문자열을 숫자로 매핑하려 할 때)

해결 방법

• 숫자 타입 필드를 Integer, Long과 같은 랩퍼 타입으로 선언해 nullable 처리
• 사용자 입력값이라면 사전 검증 로직 추가
• 필요 시 커스텀 Deserializer로 방어 처리

---

3. 날짜 처리 오류 – JavaTimeModule 미등록

증상

com.fasterxml.jackson.databind.exc.InvalidDefinitionException:
No serializer found for class java.time.LocalDateTime

원인

LocalDate, LocalDateTime, ZonedDateTime 등을 처리하기 위해 필요한 jackson-datatype-jsr310 모듈이 등록되지 않은 경우

해결 방법

<dependency>
  <groupId>com.fasterxml.jackson.datatype</groupId>
  <artifactId>jackson-datatype-jsr310</artifactId>
</dependency>

ObjectMapper mapper = new ObjectMapper();
mapper.registerModule(new JavaTimeModule());

Spring Boot 2.x 이상에서는 자동 등록됨. 단, 수동 ObjectMapper 사용 시 직접 등록 필요.

---

4. HttpMessageNotReadableException: 요청 바디 파싱 실패

증상

400 Bad Request: Required request body is missing

원인

• @RequestBody가 붙은 메서드에 JSON이 오지 않음
• 잘못된 JSON 포맷 전달 (, 누락, 중괄호 닫힘 누락 등)

해결 방법

• 클라이언트에서 Content-Type이 application/json인지 확인
• 요청 본문이 JSON 포맷에 맞는지 확인 (JSON Validator 사용 추천)
• 테스트 시 curl, Postman 등에서 구조 확인

---

5. JsonMappingException: enum 역직렬화 실패

증상

Cannot deserialize value of type `Role` from String "admin"

원인

JSON 값이 Enum의 이름과 정확히 일치하지 않을 경우

해결 방법

mapper.configure(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS, true);

또는 안전하게 처리하는 커스텀 Deserializer 적용

@JsonCreator
public static Role from(String value) {
    try {
        return Role.valueOf(value.toUpperCase());
    } catch (Exception e) {
        return Role.USER;
    }
}

---

6. 순환 참조 오류 – StackOverflowError

증상

com.fasterxml.jackson.databind.JsonMappingException: Infinite recursion

원인

A → B → A 같은 순환 구조를 가진 객체를 직렬화하려 할 때 발생

해결 방법

@JsonManagedReference
private B b;

@JsonBackReference
private A a;

또는 순환 방지 설정:

mapper.configure(SerializationFeature.FAIL_ON_SELF_REFERENCES, false);

단, 순환 참조가 불필요한 응답이라면 DTO 분리를 고려하는 것이 유지보수에 더 좋습니다.

---

7. @JsonProperty가 무시됨

증상

• JSON 필드명이 의도한 대로 나오지 않음
• Snake case 설정을 했지만 필드명이 camelCase로 출력됨

원인

• 필드에 @JsonProperty를 붙였지만, Getter/Setter에만 영향 주는 라이브러리 설정 때문일 수 있음
• 혹은 @JsonNaming 설정 충돌

해결 방법

• getter/setter 대신 필드 기반 접근 설정 적용:

mapper.setVisibility(PropertyAccessor.FIELD, JsonAutoDetect.Visibility.ANY);

• 단, 프로젝트 전반에 영향을 줄 수 있으므로 신중하게 적용

---

결론: 메시지 해석이 문제 해결의 출발점

Jackson 관련 오류는 대체로 친절한 예외 메시지를 제공합니다.
핵심은 메시지를 정확히 읽고, 해당 필드와 매핑 구조를 점검하는 것입니다.

Jackson은 강력하지만, Java의 엄격한 타입 시스템과 충돌할 여지가 있기 때문에
DTO의 필드 정의와 JSON 구조를 반드시 일치시켜야 합니다.