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

Spring Boot + Jackson 환경에서 JSON 처리 시 자주 발생하는 오류와 그 해결법을 정리합니다. JsonParseException, UnrecognizedPropertyException, 날짜 포맷, Enum 처리 오류 등 실전 사례 중심의 트러블슈팅 가이드입니다.

---

Jackson은 Java JSON 처리에 매우 강력한 도구이지만, 실무에서는 예상치 못한 오류가 종종 발생합니다. 특히 외부 API 요청, 클라이언트-서버 간 형식 불일치, DTO 설계 미흡 등이 원인이 되는 경우가 많습니다.

이 글에서는 Spring Boot 환경에서 발생할 수 있는 대표적인 JSON 처리 오류 7가지와 그 해결 전략을 명확히 정리해보겠습니다.

---

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

에러 메시지

UnrecognizedPropertyException: Unrecognized field "unknownField"

원인

• JSON에 포함된 필드가 Java DTO에 정의되어 있지 않음
• Jackson은 기본적으로 DTO에 없는 필드를 허용하지 않음

해결 방법

• 전역 설정으로 무시 처리

spring:
  jackson:
    deserialization:
      fail-on-unknown-properties: false

• 또는 클래스에 설정

@JsonIgnoreProperties(ignoreUnknown = true)
public class User { ... }

---

2. JsonParseException – 비표준 JSON 문법 오류

에러 예시

{ name: '홍길동' }  // 따옴표 없음, 단일 따옴표 사용

JsonParseException: Unexpected character ('n' (code 110))

해결 방법

ObjectMapper mapper = new ObjectMapper();
mapper.configure(JsonParser.Feature.ALLOW_UNQUOTED_FIELD_NAMES, true);
mapper.configure(JsonParser.Feature.ALLOW_SINGLE_QUOTES, true);

보안상 위험할 수 있으므로 외부 요청에는 사용 금지.

---

3. 날짜 포맷 오류 – InvalidFormatException

예시

{ "createdAt": "2024-10-01 14:00:00" }

@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss")
private LocalDateTime createdAt;

→ 포맷 불일치로 역직렬화 실패

해결 방법

• JSON 포맷을 @JsonFormat과 일치시킴
• 또는 application.yml에서 전역 설정

spring:
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss

---

4. Enum 역직렬화 오류

{ "role": "admin" }

public enum Role { ADMIN, USER }

InvalidFormatException: Cannot deserialize value of type `Role`

해결 방법

• 대소문자 무시 설정

mapper.configure(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS, true);

• 또는 커스텀 Deserializer 구현

---

5. Optional 타입 역직렬화 오류

private Optional<String> email;

문제

• jackson-datatype-jdk8 모듈이 누락되면 역직렬화 실패

해결 방법

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

mapper.registerModule(new Jdk8Module());

---

6. HttpMessageNotReadableException – 컨트롤러 파싱 실패

@PostMapping("/login")
public void login(@RequestBody LoginRequest req)

→ JSON 구조 불일치, 필드명 오류, 중괄호 누락 등 다양한 이유로 발생

해결 방법

• DTO 필드명을 JSON 구조에 맞게 확인
• 필수 필드 누락 여부 검토
• JSON 파싱 오류 상세 로그 확인

대부분은 JsonMappingException이나 JsonParseException이 내부 원인입니다.

---

7. JSON 필드 노출 불일치 – snake_case ↔ camelCase

문제

JSON에는 user_name, DTO는 userName → 매핑 실패

해결 방법

• 전역 설정:

spring:
  jackson:
    property-naming-strategy: SNAKE_CASE

• 클래스 단위 설정:

@JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)
public class User { ... }

---

실무 팁 요약

에러 유형 해결 키워드

알 수 없는 필드	@JsonIgnoreProperties, FAIL_ON_UNKNOWN_PROPERTIES
잘못된 JSON 문법	ALLOW_UNQUOTED_FIELD_NAMES, ALLOW_SINGLE_QUOTES
날짜 포맷 오류	@JsonFormat, application.yml 설정
Enum 오류	ACCEPT_CASE_INSENSITIVE_ENUMS, Custom Deserializer
Optional 오류	jackson-datatype-jdk8
역직렬화 실패	JSON 구조 검토 + DTO 필드 검증
네이밍 전략 불일치	property-naming-strategy: SNAKE_CASE