Java Gson @Since 어노테이션 완벽 가이드 – 버전별 필드 직렬화 방법

Gson 라이브러리의 @Since 어노테이션은 GsonBuilder 클래스의 setVersion() 메서드와 함께 사용됩니다. 이 어노테이션은 Java 클래스의 특정 필드에 적용할 수 있으며, float 타입의 버전 번호를 인자로 받습니다. 여기서 지정한 버전 번호는 해당 필드가 직렬화(serialize)되기 시작하는 시점을 의미하며, 역직렬화(deserialize) 과정에도 동일하게 적용됩니다.

@Since 어노테이션 문법

@Documented
@Retention(value=RUNTIME)
@Target(value={FIELD,TYPE})
public @interface Since

@Target이 FIELD와 TYPE을 허용하므로, 필드뿐만 아니라 클래스 단위에도 적용할 수 있다는 점도 참고하세요.

예제 코드

아래 예제는 Employee 객체를 생성하고, setVersion() 메서드로 버전을 0.5 → 1.0 → 1.1 순으로 변경해가며 JSON 출력 결과가 어떻게 달라지는지 보여줍니다.

import com.google.gson.annotations.Since;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class GsonSinceAnnotationTest {
    public static void main(String[] args) {
        Employee emp = new Employee();
        emp.setEmployeeName("Raja Ramesh");
        emp.setEmployeeId(125);
        emp.setEmployeeTechnology("Java");
        emp.setEmploeeAddress("Hyderabad");

        System.out.println("버전 0.5 기준");
        GsonBuilder gsonBuilder = new GsonBuilder();
        Gson gson = gsonBuilder.setPrettyPrinting().setVersion(0.5).create();
        String jsonString = gson.toJson(emp);
        System.out.println(jsonString);

        System.out.println("버전 1.0 기준");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.0).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);

        System.out.println("버전 1.1 기준");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.1).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);
    }
}

// Employee 클래스
class Employee {
    private String empName;
    private int empId;

    @Since(1.0)
    private String empTech;

    @Since(1.1)
    private String empAddress;

    public String getEmployeeName() {
        return empName;
    }
    public void setEmployeeName(String empName) {
        this.empName = empName;
    }
    public int getEmployeeId() {
        return empId;
    }
    public void setEmployeeId(int empId) {
        this.empId = empId;
    }
    public String getEmployeeTechnology() {
        return empTech;
    }
    public void setEmployeeTechnology(String empTech) {
        this.empTech = empTech;
    }
    public String getEmploeeAddress() {
        return empAddress;
    }
    public void setEmploeeAddress(String empAddress) {
        this.empAddress = empAddress;
    }
}

실행 결과

버전 0.5 기준
{
    "empName": "Raja Ramesh",
    "empId": 125
}
버전 1.0 기준
{
    "empName": "Raja Ramesh",
    "empId": 125,
    "empTech": "Java"
}
버전 1.1 기준
{
    "empName": "Raja Ramesh",
    "empId": 125,
    "empTech": "Java",
    "empAddress": "Hyderabad"
}

결과 분석

• 버전 0.5: @Since 어노테이션이 붙지 않은 empName, empId 필드만 직렬화됩니다.
• 버전 1.0: @Since(1.0)이 선언된 empTech 필드가 추가로 포함됩니다.
• 버전 1.1: @Since(1.1)이 선언된 empAddress 필드까지 모두 포함되어 전체 필드가 직렬화됩니다.

이처럼 @Since 어노테이션을 활용하면 API 버전업에 따라 새롭게 추가된 필드를 하위 버전 클라이언트에는 노출하지 않으면서, 상위 버전에서는 정상적으로 제공할 수 있어 API 하위 호환성 관리에 매우 유용합니다.