Java Gson의 @SerializedName 어노테이션 완벽 가이드: 필드 이름 매핑 방법

Java에서 JSON 직렬화 작업을 할 때 Gson 라이브러리는 가장 널리 사용되는 도구 중 하나입니다. 그중 @SerializedName 어노테이션은 실제 필드 이름과 다른 이름으로 필드를 직렬화하거나 역직렬화해야 할 때 유용하게 사용됩니다.

예를 들어, Java 클래스의 필드명은 personId이지만 JSON 출력 시에는 id라는 이름으로 표현하고 싶은 경우가 있습니다. 이럴 때 @SerializedName 어노테이션에 원하는 직렬화 이름을 속성 값으로 지정하면, Gson이 해당 이름으로 필드를 읽거나 쓰도록 보장해 줍니다.

@SerializedName 어노테이션 문법

@SerializedName은 런타임(RUNTIME)까지 유지되며, 필드(FIELD)와 메서드(METHOD)에 적용할 수 있는 어노테이션입니다. 선언 구조는 다음과 같습니다.

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

사용 예제

아래 예제에서는 Person 클래스의 personId와 personName 필드에 각각 "id"와 "name"이라는 직렬화 이름을 지정했습니다. 반면 personAddress 필드에는 어노테이션을 적용하지 않아 원래 필드명 그대로 출력됩니다.

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

public class SerializedNameTest {
    public static void main(String args[]) {
        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        Person person = new Person(115, "Raja Ramesh", "Hyderabad");
        String jsonStr = gson.toJson(person);
        System.out.println(jsonStr);
    }
}

// Person 클래스
class Person {
    @SerializedName("id")
    private int personId;

    @SerializedName("name")
    private String personName;

    private String personAddress;

    public Person(int personId, String personName, String personAddress) {
        this.personId = personId;
        this.personName = personName;
        this.personAddress = personAddress;
    }

    public int getPersonId() {
        return personId;
    }

    public String getPersonName() {
        return personName;
    }

    public String getPersonAddress() {
        return personAddress;
    }
}

실행 결과

위 코드를 실행하면 다음과 같은 JSON 문자열이 출력됩니다. 어노테이션이 적용된 필드는 지정한 이름으로, 적용되지 않은 필드는 원래 이름으로 변환된 것을 확인할 수 있습니다.

{
  "id": 115,
  "name": "Raja Ramesh",
  "personAddress": "Hyderabad"
}

정리

@SerializedName 어노테이션을 활용하면 Java 객체의 필드명과 JSON 키 이름을 자유롭게 매핑할 수 있습니다. 외부 API의 응답 형식에 맞춰야 하거나, 코드 내부 명명 규칙(카멜 케이스 등)과 JSON 키 naming 규칙(스네이크 케이스 등)이 다를 때 특히 유용합니다. 또한 역직렬화 시에도 동일하게 적용되므로, JSON 데이터를 Java 객체로 변환할 때도 일관성 있게 동작합니다.