Jackson의 @JsonProperty로 JSON 키와 Java 필드 매핑하기

API를 개발하다 보면 클라이언트와 주고받는 JSON 데이터의 키 이름이 Java 객체의 필드 이름과 일치하지 않는 경우가 존재합니다.이런 경우 Jackson 라이브러리의 @JsonProperty 어노테이션을 활용하여 매핑 문제를 쉽게 해결할 수 있습니다.이 글에서는 @JsonProperty의 개념과 실제 사용법을 코드 예제와 함께 알아보겠습니다.

@JsonProperty란?

@JsonProperty는 Jackson 라이브러리에서 제공하는 어노테이션으로, Java 객체와 JSON 데이터 간의 필드 매핑을 제어할 수 있게 해줍니다. 이 어노테이션을 활용하면 Java 객체의 필드 이름과 JSON의 키 이름이 다르더라도 정확하게 매핑할 수 있습니다.

직렬화와 역직렬화 이해하기

먼저 직렬화와 역직렬화의 개념을 간단하게 살펴보겠습니다.

직렬화 : Java 객체를 JSON으로 변환하는 과정
역직렬화 : 직렬화의 반대로써 JSON을 Java 객체로 변환하는 과정

기본적으로 Jackson 라이브러리는 Java 객체의 필드 이름을 그대로 JSON 키로 사용합니다.

class Person {
    String name;
    int age;
    ...
}
//위 객체를 json으로 변환하면 아래와 같다.
// { "name" : "john", "age" : 123 }

@JsonProperty 활용하기

@JsonProperty 어노테이션을 사용하면 Java 필드와 JSON 키 간의 매핑을 지정할 수 있습니다.
아래 예시에서는 Java 객체의 필드명은 camelCase를 사용하고, JSON에서는 대문자 키를 사용하도록 매핑해 보겠습니다.

class Person {

    @JsonProperty("NAME")
    String name;

    @JsonProperty("AGE")
    int age;

    // getter와 setter 생략
}

이제 위의 클래스를 사용하여 JSON 데이터를 직렬화하면 다음과 같은 결과가 나오게 됩니다.

{
  "NAME": "John",
  "AGE": 30
}

실제 사용 예제

직렬화 예제

Person person = new Person();
person.setName("Alice");
person.setAge(25);

ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(person);

System.out.println(json);  // {"NAME":"Alice","AGE":25} 출력

역직렬화 예제

// JSON 문자열
String json = "{\"NAME\":\"John\",\"AGE\":30}";

// ObjectMapper 생성
ObjectMapper mapper = new ObjectMapper();

// JSON을 Person 객체로 변환
Person person = mapper.readValue(json, Person.class);

System.out.println(person.getName());  // John 출력
System.out.println(person.getAge());   // 30 출력

결론

Jackson의 @JsonProperty 어노테이션은 REST API 개발 시 Java 객체와 JSON 데이터 간의 불일치 문제를 해결하는 도구이다. 이를 통해 백엔드 코드의 명명 규칙을 유지하면서 API 명세어 맞는 JSON 데이터를 제공할 수 있고 레거시 시스템과의 통합이나 외부 API 연동 시에도 유연한 대응이 가능하다.