Java Jackson @JsonAlias 어노테이션으로 필드 대체 이름 정의하는 방법

Java에서 Jackson 라이브러리를 사용하다 보면 JSON의 키 이름과 Java 객체의 필드 이름이 서로 다른 경우가 자주 발생합니다. 이럴 때 @JsonAlias 어노테이션을 사용하면 역직렬화(deserialization) 과정에서 하나 이상의 대체 이름(별칭)을 정의할 수 있습니다.

즉, JSON 데이터를 Java 객체로 변환할 때 여러 개의 다른 키 이름으로 들어오는 값을 동일한 필드에 매핑할 수 있습니다. 반면 직렬화(serialization), 즉 Java 객체에서 JSON을 생성할 때는 별칭(alias)이 아닌 실제 논리적 프로퍼티 이름만 사용된다는 점에 유의해야 합니다.

@JsonAlias 문법

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

@JsonAlias는 필드, 메서드, 파라미터 등에 적용할 수 있으며, 런타임에 유지되는 어노테이션입니다.

예제 코드

아래 예제에서는 @JsonProperty로 기본 JSON 키 이름을 지정하고, @JsonAlias를 통해 역직렬화 시 허용할 대체 이름들을 추가로 정의했습니다.

import com.fasterxml.jackson.annotation.*;
import com.fasterxml.jackson.core.*;
import com.fasterxml.jackson.databind.*;
import java.io.*;
public class ObjectToJsonTest {
   public static void main(String[] args) throws JsonProcessingException {
      ObjectMapper mapper = new ObjectMapper();
      Technology tech = new Technology("Java", "Oracle");
      Employee emp = new Employee(110, "Raja", tech);
      String jsonWriter = mapper.writerWithDefaultPrettyPrinter().writeValueAsString(emp);
      System.out.println(jsonWriter);
   }
}
// Technology 클래스
class Technology {
   @JsonProperty("skill")
   private String skill;
   @JsonProperty("subSkill")
   @JsonAlias({"sSkill", "mySubSkill"})
   private String subSkill;
   public Technology(){}
   public Technology(String skill, String subSkill) {
      this.skill = skill;
      this.subSkill = subSkill;
   }
   public String getSkill() {
      return skill;
   }
   public void setSkill(String skill) {
      this.skill = skill;
   }
   public String getSubSkill() {
      return subSkill;
   }
   public void setSubSkill(String subSkill) {
      this.subSkill = subSkill;
   }
}
// Employee 클래스
class Employee {
   @JsonProperty("empId")
   private Integer id;
   @JsonProperty("empName")
   @JsonAlias({"ename", "myename"})
   private String name;
   @JsonProperty("empTechnology")
   private Technology tech;
   public Employee(){}
   public Employee(Integer id, String name, Technology tech){
      this.id = id;
      this.name = name;
      this.tech = tech;
   }
   public Integer getId() {
      return id;
   }
   public void setId(Integer id) {
      this.id = id;
   }
   public String getName() {
      return name;
   }
   public void setName(String name) {
      this.name = name;
   }
   public Technology getTechnology() {
      return tech;
   }
   public void setTechnology(Technology tech) {
      this.tech = tech;
   }
}

실행 결과

위 코드를 실행하면 직렬화 시 별칭이 아닌 @JsonProperty로 지정한 실제 프로퍼티 이름만 출력되는 것을 확인할 수 있습니다.

{
 "technology" : {
 "skill" : "Java",
 "subSkill" : "Oracle"
 },
 "empId" : 110,
 "empName" : "Raja",
 "empTechnology" : {
 "skill" : "Java",
 "subSkill" : "Oracle"
 }
}

정리

• @JsonAlias는 역직렬화 시 여러 대체 키 이름을 허용하여 유연한 JSON 매핑을 가능하게 합니다.
• 직렬화 시에는 별칭이 아닌 @JsonProperty 또는 기본 프로퍼티 이름만 사용됩니다.
• 외부 API 응답처럼 동일한 의미의 데이터가 여러 키 이름으로 전달될 수 있는 상황에서 특히 유용합니다.