@JsonIgnoreProperties(ignoreUnknown = true)는 꼭 필요할까?

API 개발을 하다 보면 외부 API를 호출하거나 클라이언트로부터 데이터를 받을 때 DTO(Data Transfer Object)를 설계하게 됩니다. 이때 자주 마주치는 어노테이션이 바로 @JsonIgnoreProperties(ignoreUnknown = true)입니다.

단순히 "에러를 방지하기 위해" 사용하는 용도가 아닌 이 설정이 왜 중요한지, 그리고 어떤 상황에서 필수적인지 에 대하여 알아보겠습니다.

 

※ 해당 어노테이션은 JSON을 생성(serialize) 할 때가 아니라 JSON을 객체로 변환(deserialize) 할 때 의미가 있습니다.

• JSON -> Java 객체로 변환할 때(JSON 역직렬화). 즉, 입력(JSON 수신) 용도입니다.

기본 동작: Jackson의 엄격한 잣대

Java의 대표적인 JSON 라이브러리인 Jackson은 기본적으로 엄격한 매핑을 지향합니다.

JSON 데이터에는 age라는 필드가 있는데, 이를 받아주는 Java DTO 객체에 age 필드가 없다면 Jackson은 UnrecognizedPropertyException을 던지며 역직렬화(Deserialization)를 중단합니다.

// JSON 데이터: {"id": 1, "name": "json", "age": 20}
public class UserDto {
    private Long id;
    private String name;
    // age 필드가 없음! -> Exception 발생
}

@JsonIgnoreProperties(ignoreUnknown = true)의 역할

이 어노테이션은 내가 정의하지 않은 필드가 JSON에 들어있어도 무시하고 진행해라라는 지시어입니다. 클래스 레벨에 선언하면 DTO에 명시되지 않은 필드는 무시된 채 선언된 필드만 매핑됩니다.

---

왜 사용해야 하는가? (주요 사례)

① 외부 API와의 하위 호환성 (가장 중요)

내가 제어할 수 없는 외부 API(예: 결제 게이트웨이, 공공 데이터 API)를 호출할 때 특히 중요합니다.

• 외부 서비스에서 업데이트를 통해 JSON 응답에 새로운 필드를 추가했다고 가정해 봅시다.
• 이 설정이 없다면, 우리 시스템은 갑자기 발생하는 UnrecognizedPropertyException 때문에 서비스 전체가 마비될 수 있습니다.
• 유연한 수용성을 위해 외부 연동 DTO에는 필수적으로 사용됩니다.

② 대규모 JSON에서 필요한 데이터만 추출할 때

응답 데이터는 수십 개의 필드를 포함하고 있지만, 우리 서비스에서 필요한 데이터는 단 2~3개뿐인 경우가 있습니다. 모든 필드를 DTO에 일일이 선언하는 것은 리소스 낭비입니다. 이때 필요한 필드만 정의하고 나머지는 무시하도록 설정하여 코드를 간결하게 유지할 수 있습니다.

③ 보안 및 오버포스팅(Over-posting) 방지

클라이언트가 악의적으로 혹은 실수로 DTO에 정의되지 않은 추가 데이터를 보낼 때, 이를 무시함으로써 원치 않는 데이터가 로직에 개입하는 것을 차단합니다.

---

응답(JSON 생성)에는 왜 필요 없는가?

상황: Controller에서 응답 JSON을 만드는 경우

@GetMapping("/sample")
public SampleDto response() {
    return new SampleDto("1");
}

이 흐름은: Java 객체 → JSON (직렬화)

• Jackson은 객체에 있는 필드만 JSON으로 생성합니다.
• JSON에 “알 수 없는 필드”라는 개념 자체가 없습니다.
• 따라서 ignoreUnknown이 적용될 상황이 없습니다.

응답 전용 DTO에는 붙여도 효과가 없습니다.

---

전역 설정 vs 개별 설정

매번 DTO에 어노테이션을 붙이는 것이 번거롭다면 프로젝트 전체에 적용할 수도 있습니다.

Spring Boot 설정 (application.yml):

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

또는 ObjectMapper 빈 등록 시:

@Bean
public ObjectMapper objectMapper() {
    return new ObjectMapper()
        .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
}

---

결론

결론적으로, MSA(Microservices Architecture) 환경이나 외부 API 연동이 잦은 현대 백엔드 개발에서 이 설정은 필수에 가깝습니다.

• 운영 환경: 시스템의 회복 탄력성(Resilience)을 위해 ignoreUnknown = true를 권장합니다. 예상치 못한 필드 추가로 인해 시스템이 다운되는 것은 막아야 하기 때문입니다.
• 개발 환경: 필드 매핑이 정확한지 확인해야 하는 엄격한 검증이 필요할 때만 제한적으로 기본 설정을 유지하는 것이 좋습니다.