JavaのGsonで@Sinceアノテーションを使う方法｜バージョン別のフィールド制御を解説

Gsonライブラリの@Sinceアノテーションは、GsonBuilderクラスのsetVersion()メソッドと組み合わせて使用します。このアノテーションはJavaクラスのフィールドに付与でき、引数としてfloat型のバージョン番号を受け取ります。ここで指定したバージョン番号は「そのフィールドがシリアライズ（JSON出力）対象となるバージョン」を表しており、デシリアライズ（JSON読み込み）の際にも同様に機能します。

これにより、アプリケーションのバージョンアップに伴って追加されたフィールドを、古いバージョンのJSONには含めない、といった柔軟なバージョン管理が可能になります。

@Sinceアノテーションの構文

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

コード例

以下の例では、Employeeクラスの各フィールドに@Sinceアノテーションを付与し、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("Since 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("Since version 1.0");
        gsonBuilder = new GsonBuilder();
        gson = gsonBuilder.setPrettyPrinting().setVersion(1.0).create();
        jsonString = gson.toJson(emp);
        System.out.println(jsonString);

        System.out.println("Since 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;
    @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;
    }
}

実行結果

Since version 0.5
{
  "empName": "Raja Ramesh",
  "empId": 125
}
Since version 1.0
{
  "empName": "Raja Ramesh",
  "empId": 125,
  "empTech": "Java"
}
Since version 1.1
{
  "empName": "Raja Ramesh",
  "empId": 125,
  "empTech": "Java",
  "empAddress": "Hyderabad"
}

実行結果のポイント

実行結果から、以下の動作が確認できます。

• バージョン0.5の場合：empNameとempIdには@Sinceが付与されていないため、常に出力されます。
• バージョン1.0の場合：@Since(1.0)が付いたempTechが出力に追加されます。
• バージョン1.1の場合：@Since(1.1)が付いたempAddressも含まれ、すべてのフィールドが出力されます。

つまり、setVersion()に指定したバージョン以上の@Sinceが付与されたフィールドだけがJSONに含まれる仕組みです。APIの互換性維持や段階的なデータモデルの拡張など、バージョン管理が必要な場面で非常に役立ちます。