Java Gson @Until 어노테이션으로 JSON 버전 관리하는 방법

Gson 라이브러리의 @Until 어노테이션은 GsonBuilder 클래스의 setVersion() 메서드와 함께 사용되는 기능입니다. 이 어노테이션은 Java 클래스의 특정 필드에 적용할 수 있으며, float 타입의 버전 번호를 인수로 받습니다. 객체를 직렬화할 때 설정한 버전이 이 값보다 작으면 해당 필드가 JSON에 포함되고, 그렇지 않으면 JSON에서 제외됩니다.

이러한 버전 관리 기능은 웹 서비스에서 API 버전에 따라 서로 다른 JSON 응답 구조를 제공해야 할 때 특히 유용합니다. 예를 들어 구버전 클라이언트에는 모든 필드를 노출하고, 신버전 클라이언트에는 특정 필드를 숨기는 처리를 어노테이션 하나만으로 손쉽게 구현할 수 있습니다.

@Until 어노테이션 문법

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

@Until 어노테이션 예제

다음 예제는 Employee 클래스의 empTech와 empAddress 필드에 @Until(1.1)을 적용한 뒤, 버전 0.5, 1.0, 1.1로 각각 직렬화하여 결과를 비교합니다.

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

public class GsonUntilAnnotationTest {
    public static void main(String[] args) {
        Employee emp = new Employee();
        emp.setEmployeeName("Adithya");
        emp.setEmployeeId(115);
        emp.setEmployeeTechnology("Python");
        emp.setEmploeeAddress("Pune");

        System.out.println("Using version 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("Using version 1.0");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.0).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);

        System.out.println("Using version 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;

    @Until(1.1)
    private String empTech;

    @Until(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;
    }
}

실행 결과

Using version 0.5
{
    "empName": "Adithya",
    "empId": 115,
    "empTech": "Python",
    "empAddress": "Pune"
}
Using version 1.0
{
    "empName": "Adithya",
    "empId": 115,
    "empTech": "Python",
    "empAddress": "Pune"
}
Using version 1.1
{
    "empName": "Adithya",
    "empId": 115
}

결과 분석

• 버전 0.5: @Until(1.1)로 지정한 값보다 작으므로 모든 필드가 JSON에 포함됩니다.
• 버전 1.0: 마찬가지로 1.1보다 작기 때문에 모든 필드가 그대로 직렬화됩니다.
• 버전 1.1: @Until(1.1)이 적용된 empTech와 empAddress 필드가 제외되고 empName과 empId만 출력됩니다.

참고로 @Since 어노테이션은 @Until과 반대되는 개념으로, 지정한 버전부터 해당 필드를 JSON에 포함시킵니다. 두 어노테이션을 함께 활용하면 API 버전 전환 시점에 필드를 훨씬 정교하게 관리할 수 있습니다.