Java Jackson의 @JsonRootName 어노테이션 완벽 가이드

Java에서 JSON 직렬화를 다룰 때, 출력되는 JSON의 최상위 루트(root) 요소를 특정 이름으로 감싸야 하는 경우가 종종 있습니다. 이럴 때 유용하게 사용할 수 있는 것이 바로 Jackson 라이브러리의 @JsonRootName 어노테이션입니다.

@JsonRootName이란?

@JsonRootName 어노테이션은 객체를 직렬화할 때 최상위 엘리먼트로 감싸도록 지정하는 기능을 제공합니다. 어노테이션에 원하는 이름을 파라미터로 전달하면, 해당 이름이 JSON 출력 시 루트 프로퍼티의 키(key)로 사용됩니다.

단, 이 기능이 실제로 동작하려면 SerializationFeature 열거형(enum)의 WRAP_ROOT_VALUE 기능을 활성화해야 합니다. 이 옵션을 켜면 루트 값이 단일 프로퍼티를 가진 JSON 객체로 감싸지며, 그 키가 바로 @JsonRootName으로 지정한 이름이 됩니다.

사용 예제

다음은 Employee 클래스에 @JsonRootName 어노테이션을 적용하고, ObjectMapper에서 WRAP_ROOT_VALUE 기능을 활성화하여 JSON을 생성하는 예제입니다.

import com.fasterxml.jackson.annotation.JsonRootName;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.SerializationFeature;

public class JsonRootNameAnnotationTest {
    public static void main(String args[]) throws JsonProcessingException {
        ObjectMapper mapper = new ObjectMapper();
        String jsonString = mapper.enable(SerializationFeature.WRAP_ROOT_VALUE)
                                  .writeValueAsString(new Employee());
        System.out.println(jsonString);
    }
}

@JsonRootName(value = "user")
class Employee {
    public int empId = 125;
    public String empName = "Raja Ramesh";
}

실행 결과

{"user":{"empId":125,"empName":"Raja Ramesh"}}

동작 방식 정리

실행 결과를 보면 일반적인 직렬화와 달리, JSON 객체가 "user"라는 키로 한 번 감싸진 것을 확인할 수 있습니다. 만약 WRAP_ROOT_VALUE를 활성화하지 않으면 결과는 {"empId":125,"empName":"Raja Ramesh"}처럼 루트 없이 출력됩니다.

정리하면 다음과 같습니다.

• @JsonRootName(value = "user"): 직렬화될 객체의 루트 이름을 "user"로 지정합니다.
• SerializationFeature.WRAP_ROOT_VALUE: 루트 값을 단일 프로퍼티 JSON 객체로 감싸는 기능을 활성화합니다.

이 조합은 REST API 응답 형식을 표준화하거나, XML 변환 시 루트 엘리먼트 이름을 제어해야 하는 상황 등에서 특히 유용하게 활용됩니다.