[TroubleShooting] Jackson이 싫어하는 단일 필드

👀 현재 상황 및 배경 설명

🔽 DTO 흐름

코드의 가독성과 흐름을 깔끔하게 유지하기 위해 클래스 간 정보를 전달할 때 DTO 클래스를 활용하고 있다. Swagger를 사용하고 있으므로, DTO 클래스의 명명 규칙을 백엔드 내부적으로 통일하였다.

• 입력을 전달하는 DTO: ~Request
• 출력을 전달하는 DTO: ~Response
• 내부적으로 정보를 전달하는 DTO: ~Dto

 

▶ 구현 코드

🔽 MemberRegisterRequest DTO

@Getter
@Builder
@RequiredArgsConstructor
public class MemberRegisterRequest {

    @Schema(description = "회원의 이름", example = "이소은", required = true)
    private final String name;

    @Schema(description = "회원의 닉네임", example = "twocowsilver", required = true)
    private final String nickname;

    @Schema(description = "회원의 지역", example = "동대문구", required = true)
    private final String location;

    ...
}

🔽 MemberInfoResponse DTO

@Getter
@Builder
@RequiredArgsConstructor
public class MemberInfoResponse {

    @Schema(description = "회원의 Id", example = "1")
    private final Long id;

    @Schema(description = "회원의 이름", example = "이소은")
    private final String name;

    @Schema(description = "회원의 닉네임", example = "twocowsilver")
    private final String nickname;

    ...
}

 

 

🚨 문제 상황

DTO에 여러 개의 필드가 있을 때는 문제가 없지만, 단일 필드를 가진 DTO만 JSON parse error가 발생한다.

🔽 문제가 발생하는 DTO 클래스

@Getter
@Builder
@RequiredArgsConstructor
public class OrganizationJoinRequest {

    @Schema(description = "가입 한줄 소개", example = "안녕하세요", required = true)
    private final String introduction;
}

@Getter
@Builder
@RequiredArgsConstructor
public class RefreshTokenRequest {

    @Schema(description = "JWT 갱신을 위한 Refresh Token", example = "eyJ...", required = true)
    private final String refreshToken;
}

🔽 에러 로그

 

 

✏️ 원인 분석

구글링과 GPT를 통해 확인한 결과, 기본 생성자 어노테이션 @NoArgsConstructor을 지정해야 한다는 답변이 많았다. 그런데 필드가 여러 개인 DTO 클래스에는 기본 생성자를 지정하지 않아도 정상적으로 작동하는 반면, 필드가 하나인 DTO 클래스만 에러가 발생하는 것이 이상했다.

Jackson 라이브러리의 GitHub 이슈를 통해 그 원인을 파악할 수 있었다.

단일 필드 DTO의 경우, Jackson은 기본적으로 단일-인자 생성자 호출을 통해 객체를 생성하려 한다. 이 과정에서 Jackson은 두 가지 방식 중 하나를 선택해야 한다.

1. Delegating 방식
   • JSON 값(단일 값)이 객체 전체에 바로 매핑될 때
   • 예: JSON "value" -> new Constructor("value")
2. Properties 방식
   • JSON의 속성-값 쌍을 통해 구성될 때
   • 예: JSON {"name": "value"} -> new Constructor(name = "value")

Jackson이 잘못된 방식을 선택하면 JSON parse error가 발생한다. 필드가 여러 개인 경우, Jackson은 자동으로 Properties 방식을 선택하므로 문제가 발생하지 않는다. 하지만 필드가 단일인 경우, Jackson은 Delegating 방식과 Properties 방식 중 하나를 선택할 수 있고, 잘못된 방식을 선택할 경우 에러가 발생한다.

현재 사례에서는 단일 필드인 DTO 클래스에서 Jackson이 JSON 값을 Object 값이 아닌 코드에 선언된 String 값으로 처리할 것으로 기대하고 Delegating 방식을 사용하려고 시도했다. 그러나 실제 JSON 데이터는 Properties 방식으로 처리되어야 하는 구조였기 때문에, 이 과정에서 에러가 발생한 것이다.

 

 

🔨 해결 방법

▶ final 키워드 삭제 (비추천)

@Builder, @RequiredArgsConstructor, final 키워드를 제거해 Jackson이 기본적으로 사용할 수 있는 구조로 변경한다.

하지만 DTO 특성상, 정보가 변경되지 않아야 한다는 점에서 좋지 않은 방법이라고 생각한다.

@Getter
public class OrganizationJoinRequest {

    @Schema(description = "가입 한줄 소개", example = "안녕하세요", required = true)
    private String introduction;
}

 

▶ 기본 생성자 강제 선언 (비추천)

기본 생성자를 @NoArgsConstructor(force = true)를 사용해 기본 생성자를 강제로 추가한다. @NoArgsConstructor만 사용할 경우 final 필드가 초기화되지 않아 기본 생성자가 생성되지 않으므로 force = true 옵션이 필요하다.

하지만 이 방식은 final 필드가 강제로 기본값(null)으로 초기화되므로, 객체가 불완전한 상태로 생성될 수 있어 좋지 않은 방법이라고 생각한다.

 

@Getter
@Builder
@RequiredArgsConstructor
@NoArgsConstructor(force = true) // 강제 선언
public class OrganizationJoinRequest {

    @Schema(description = "가입 한줄 소개", example = "안녕하세요", required = true)
    private final String introduction;
}

기본 생성자가 추가되면 해결되는 이유
Jackson이 JSON 데이터를 역직렬화(Deserialize)할 때 객체를 생성하는 방법으로 기본 생성자 또는 명시적 생성자를 사용한다. 기본 생성자가 없으면 Jackson이 객체를 생성할 수 없어서 오류가 발생한다. 반면, 기본 생성자가 추가되면 Jackson은 이를 사용해 객체를 생성한 뒤, JSON 데이터에서 추출한 속성-값 쌍을 해당 객체 필드에 매핑한다.

 

▶ @JsonCreator로 명시적 모드 설정 (추천)

@JsonCreator(mode = JsonCreator.Mode.PROPERTIES)를 사용해 Jackson이 Properties 방식을 명시적으로 사용하도록 설정한다.

@Getter
@Builder
public class OrganizationJoinRequest {

    @Schema(description = "가입 한줄 소개", example = "안녕하세요", required = true)
    private final String introduction;

    @JsonCreator(mode = JsonCreator.Mode.PROPERTIES) // Properties 모드로 설정
    public OrganizationJoinRequest(@JsonProperty("introduction") String introduction) {
        this.introduction = introduction;
    }
}

 

▶ Jackson 전역 설정 변경

Jackson 2.12 이상 버전에서는 전역적으로 Properties 모드를 기본값으로 설정할 수 있다.

@Bean
public ObjectMapper objectMapper() {
    ObjectMapper mapper = new ObjectMapper();
    mapper.configure(MapperFeature.INFER_CREATOR_FROM_CONSTRUCTOR_PROPERTIES, true);
    return mapper;
}

 

▶ @ConstructorProperties 사용

@ConstructorProperties를 사용해 생성자와 JSON 속성 간의 매핑 정보를 제공하여 Jackson이 Properties 방식을 사용하도록 유도한다.

@Getter
@Builder
@RequiredArgsConstructor
public class OrganizationJoinRequest {

    @Schema(description = "가입 한줄 소개", example = "안녕하세요", required = true)
    private final String introduction;

    @ConstructorProperties({"introduction"}) // 생성자 매핑 정보 제공
    public OrganizationJoinRequest(String introduction) {
        this.introduction = introduction;
    }
}

 

 

🔍 결과 관찰

JSON 데이터가 정상적으로 반환되며, 정상적으로 작동함을 확인할 수 있었다.

 

 

💡 고찰

사실 프로젝트를 진행하면서 단일 필드 DTO만 기본 생성자를 생성해줘야 한다는 점이 이상하다고 생각은 하고 있었지만, 시간에 쫓기다 보니 final 키워드를 삭제하는 방법으로 급하게 에러를 해결했었다. 프로젝트가 끝난 후, 당시 느꼈던 의문점을 바탕으로 트러블슈팅을 진행했고, 문제의 원인이 생각보다 의미 있는 부분에 있었다는 것을 알게 되었다. 이 과정을 통해 JSON이 객체를 파싱하는 방식을 이해할 수 있는 기회가 되었다.

 

 

📍 참고 자료

• Jackson fails to deserialize 1 field POJO #3085
• JSON 필드 하나면 왜 Jackson 파업함?