Java Gson에서 @SerializedName 어노테이션으로 JSON 필드 이름 변경하는 방법

Java에서 JSON 직렬화를 다룰 때, Java 객체의 필드 이름과 실제 JSON 키 이름이 일치하지 않아야 하는 경우가 자주 발생합니다. 예를 들어 Java에서는 카멜 케이스(camelCase)를 사용하지만, 외부 API에서는 스네이크 케이스(snake_case)를 요구하는 경우가 대표적입니다.

이럴 때 Gson 라이브러리가 제공하는 @SerializedName 어노테이션을 사용하면 됩니다. 이 어노테이션을 필드에 지정하면, 직렬화 시 해당 값이 JSON의 필드 이름으로 사용됩니다.

@SerializedName 어노테이션의 특징

@SerializedName 어노테이션은 Gson 인스턴스에 설정된 모든 FieldNamingPolicy를 재정의(override)할 수 있습니다. 여기에는 기본 필드 네이밍 정책도 포함됩니다. 반대로 말하면, GsonBuilder 클래스를 통해 별도의 네이밍 정책을 설정해두었다 하더라도, @SerializedName이 붙은 필드에는 항상 지정한 이름이 우선 적용됩니다.

문법(Syntax)

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

예제 코드

다음 예제는 Employee 클래스의 firstName, lastName 필드에 @SerializedName을 적용하여, JSON 출력 시 first_name, last_name으로 변환되도록 만든 코드입니다.

import com.google.gson.annotations.*;
import com.google.gson.*;

public class SerializedNameAnnotationTest {
   public static void main(String args[]) {
      Employee emp = new Employee("Rahul", "Dev", 30, "Nagpur");
      Gson gson = new GsonBuilder().setPrettyPrinting().create(); // 보기 좋게 출력
      String jsonStr = gson.toJson(emp);
      System.out.println(jsonStr);
   }
}

// Employee 클래스
class Employee {
   @SerializedName("first_name")
   private String firstName;

   @SerializedName("last_name")
   private String lastName;

   private int age;
   private String address;

   public Employee() {
   }

   public Employee(String firstName, String lastName, int age, String address) {
      super();
      this.firstName = firstName;
      this.lastName = lastName;
      this.age = age;
      this.address = address;
   }

   public String getFirstName() {
      return firstName;
   }
   public String getLastName() {
      return lastName;
   }
   public int getAge() {
      return age;
   }
   public String getAddress() {
      return address;
   }
}

실행 결과(Output)

위 코드를 실행하면 firstName과 lastName 필드가 각각 first_name, last_name이라는 JSON 키로 직렬화된 것을 확인할 수 있습니다.

{
  "first_name": "Rahul",
  "last_name": "Dev",
  "age": 30,
  "address": "Nagpur"
}

정리

@SerializedName 어노테이션은 Java 필드 이름과 JSON 키 이름을 다르게 매핑해야 할 때 가장 간단하고 확실한 방법입니다. 특히 snake_case나 kebab-case 등 외부 시스템의 네이밍 규칙에 맞춰야 하는 상황에서 유용하며, GsonBuilder로 설정한 네이밍 정책보다 항상 우선적으로 적용된다는 점을 기억하면 됩니다.