Spring Boot DTO에서 Boolean 필드가 null이 되는 이유와 해결 방법

Source: Dev.to

Spring Boot를 사용해 REST API를 구축하고 있다면, 이상하고 답답한 문제를 마주할 수 있습니다:

요청 JSON은 명확히 boolean 값(true / false)을 전송하지만, DTO 내부에서는 그 값이 null이 됩니다.
예외도 없고, 경고도 없으며, 스택 트레이스도 없습니다.

이는 Spring Boot의 버그가 아니라 Jackson + Java Bean 네이밍 함정으로, 실제 애플리케이션에서 자주 나타납니다.

이 기사에서 배우게 될 내용

• Spring Boot DTO에서 boolean 값이 null이 되는 이유
• Jackson이 JSON 속성을 Java 필드에 매핑하는 방법
• @JsonProperty가 문제를 해결하는 이유
• 이를 영원히 방지하기 위한 권장 베스트 프랙티스

문제: DTO에서 Boolean 값이 null인 경우

요청 페이로드

{
  "isActive": true
}

DTO

public class UserRequest {

    private Boolean isActive;

    public Boolean getIsActive() {
        return isActive;
    }

    public void setIsActive(Boolean isActive) {
        this.isActive = isActive;
    }
}

컨트롤러

@PostMapping("/user")
public void createUser(@RequestBody UserRequest request) {
    System.out.println(request.getIsActive());
}

실제 출력

null

왜 이런 일이 발생하는가 (Jackson + Java Bean 규칙)

Spring Boot은 Jackson을 사용하여 JSON을 Java 객체로 변환합니다. Jackson은 Java Bean 명명 규칙을 따르며, 이는 getter와 setter 이름에 크게 의존합니다.

Jackson이 boolean 필드를 해석하는 방법

다음과 같이 필드가 선언된 경우:

private Boolean isActive;

Jackson은 다음 중 하나의 메서드 패턴을 기대합니다:

public Boolean isActive()   // for primitive boolean
// or
public Boolean getActive()

하지만 DTO에서는 다음과 같이 정의되었습니다:

public Boolean getIsActive()

불일치

• JSON 속성: isActive
• Jackson이 추론하는 Java 속성: active

이 불일치 때문에 Jackson이 값을 바인딩하지 못하고 null이 반환됩니다.

솔루션 1: @JsonProperty 사용 (빠른 해결책)

Jackson에 JSON 속성을 어떻게 매핑할지 명시적으로 알려줍니다.

import com.fasterxml.jackson.annotation.JsonProperty;

public class UserRequest {

    @JsonProperty("isActive")
    private Boolean isActive;

    public Boolean getIsActive() {
        return isActive;
    }

    public void setIsActive(Boolean isActive) {
        this.isActive = isActive;
    }
}

결과: JSON이 올바르게 매핑되고, DTO가 true / false 를 받아 null이 더 이상 발생하지 않습니다.

솔루션 2: 모범 사례 (강력히 권장)

매핑을 고치는 대신 설계를 고치세요. is 로 시작하는 boolean 필드 이름은 피합니다.

권장 DTO 설계

public class UserRequest {

    private Boolean active;

    public Boolean getActive() {
        return active;
    }

    public void setActive(Boolean active) {
        this.active = active;
    }
}

왜 이렇게 하는 것이 더 좋은가

• 완전한 Java Bean 규격 준수
• Jackson 어노테이션이 필요 없음
• 더 깔끔하고 가독성이 좋은 DTO
• 대규모 코드베이스에서 버그 감소

Spring Boot DTO에서 boolean vs Boolean

언제 사용해야 할까

• 필드가 필수인 경우 boolean을 사용합니다.
• 필드가 선택적이거나 삼값( tri‑state)인 경우 Boolean을 사용합니다.

일반적인 면접 질문

Q: Spring Boot이 boolean JSON 값을 null로 매핑하는 이유는 무엇인가요?
A: Jackson은 Java Bean 명명 규칙을 따르기 때문입니다. is 접두사가 붙은 boolean 필드는 getter, setter 또는 @JsonProperty를 올바르게 정의하지 않으면 속성 이름이 일치하지 않을 수 있습니다.

핵심 요약

• is 로 시작하는 Boolean 필드는 Jackson 매핑을 조용히 깨뜨릴 수 있습니다.
• Jackson은 필드 이름이 아니라 getter/setter 명명 규칙에 의존합니다.
• @JsonProperty 를 사용하면 문제를 명시적으로 해결할 수 있습니다.
• 베스트 프랙티스: DTO 필드에서 is 접두사를 피하세요.
• 컨트롤러 디버깅 전에 항상 DTO 설계를 검토하세요.

최종 조언

JSON이 올바르게 보이지만 DTO 값이 null인 경우:

먼저 getter와 setter 이름을 확인하세요.

이 작은 디테일이 Spring Boot 애플리케이션에서 디버깅 시간을 몇 시간씩 절약할 수 있습니다.