Java Jackson @JsonValue 어노테이션 완벽 가이드: 객체 직렬화를 원하는 대로 제어하기

@JsonValue 어노테이션은 Jackson 라이브러리에서 제공하는 강력한 기능으로, 메서드(Method) 또는 필드(Field) 수준에서 적용할 수 있습니다. 이 어노테이션을 사용하면 Java 객체가 JSON 문자열로 직렬화(Serialization)되는 방식을 개발자가 직접 정의할 수 있습니다.

일반적으로 직렬화된 객체를 출력하려면 toString() 메서드를 오버라이드(Override)해야 하지만, @JsonValue를 활용하면 별도의 로직 없이도 객체가 JSON으로 변환될 때의 출력 형식을 유연하게 지정할 수 있습니다. 즉, Jackson이 해당 메서드의 반환값을 그대로 JSON 표현으로 사용하게 됩니다.

@JsonValue의 주요 용도

• 객체 전체가 아닌 특정 값만 JSON으로 직렬화하고 싶을 때
• Enum 타입을 특정 문자열이나 숫자 값으로 변환할 때
• 기본 직렬화 규칙 대신 커스텀 형식(예: 쉼표로 구분된 문자열)을 정의하고 싶을 때

문법(Syntax)

@Target(value={ANNOTATION_TYPE, METHOD, FIELD})
@Retention(value=RUNTIME)
public @interface JsonValue

@JsonValue는 어노테이션 타입, 메서드, 필드에 적용 가능하며, 런타임 시점에 동작합니다.

실전 예제

다음은 Student 클래스에 @JsonValue를 적용하여 직렬화 결과를 커스터마이징하는 예제입니다.

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonValue;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;

public class JsonValueAnnotationTest {
    public static void main(String args[]) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        String jsonString = mapper.writeValueAsString(new Student());
        System.out.println(jsonString);
    }
}

// Student 클래스
class Student {
    @JsonProperty
    private int studentId = 115;

    @JsonProperty
    private String studentName = "Sai Adithya";

    @JsonValue
    public String toJson() {
        return this.studentName + "," + this.studentId + "," + this.toString();
    }

    @Override
    public String toString() {
        return "Student[" +
                "studentId = " + studentId +
                ", studentName = " + studentName +
                ']';
    }
}

코드 설명

• @JsonProperty: 각 필드가 JSON 속성으로 매핑되도록 지정합니다.
• @JsonValue: toJson() 메서드에 적용되어, Jackson이 객체를 직렬화할 때 이 메서드의 반환값을 JSON 결과로 사용합니다.
• ObjectMapper: Java 객체를 JSON 문자열로 변환하는 Jackson의 핵심 클래스입니다.

실행 결과(Output)

"Sai Adithya,115,Student[studentId = 115, studentName = Sai Adithya]"

실행 결과를 보면, 일반적인 JSON 객체 형태({"studentId":115,...})가 아니라 toJson() 메서드가 반환한 단일 문자열 값이 그대로 출력된 것을 확인할 수 있습니다. 이처럼 @JsonValue를 사용하면 직렬화 과정을 세밀하게 제어할 수 있습니다.

핵심 정리

@JsonValue 어노테이션은 Java 객체의 JSON 직렬화 형식을 커스터마이징해야 할 때 매우 유용합니다. 특히 Enum 값을 특정 표현으로 변환하거나, API 응답에서 특정 포맷이 요구되는 경우에 활용도가 높습니다. 다만 한 클래스 내에서 @JsonValue는 하나의 메서드 또는 필드에만 적용해야 한다는 점을 기억하세요.