JavaでGsonのバージョン管理機能を有効にする方法

Gsonライブラリは、読み書きするJavaオブジェクトに対してシンプルなバージョン管理システムを提供しています。このバージョン管理を実現するために、@Sinceアノテーションが用意されており、@Since(バージョン番号)のように記述して使用します。

Gsonインスタンスをバージョン管理対応で生成するには、GsonBuilder().setVersion()メソッドを使用します。例えばsetVersion(2.0)と指定した場合、@Sinceアノテーションに2.0以下のバージョンが設定されたフィールドのみがシリアライズ・デシリアライズの対象となります。

構文

public GsonBuilder setVersion(double ignoreVersionsAfter)

引数には、それ以降のバージョンのフィールドを無視する基準となるバージョン番号をdouble型で指定します。

コード例

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

public class VersionSupportTest {
    public static void main(String[] args) {
        Person person = new Person();
        person.firstName = "Raja";
        person.lastName = "Ramesh";

        // バージョン1.0としてGsonインスタンスを作成
        Gson gson1 = new GsonBuilder().setVersion(1.0).setPrettyPrinting().create();
        System.out.println("Version 1.0:");
        System.out.println(gson1.toJson(person));

        // バージョン2.0としてGsonインスタンスを作成
        Gson gson2 = new GsonBuilder().setVersion(2.0).setPrettyPrinting().create();
        System.out.println("Version 2.0:");
        System.out.println(gson2.toJson(person));
    }
}

// Personクラス
class Person {
    @Since(1.0)
    public String firstName;

    @Since(2.0)
    public String lastName;
}

実行結果

Version 1.0:
{
  "firstName": "Raja"
}
Version 2.0:
{
  "firstName": "Raja",
  "lastName": "Ramesh"
}

解説

上記の例では、PersonクラスのfirstNameフィールドには@Since(1.0)が、lastNameフィールドには@Since(2.0)が付与されています。

• setVersion(1.0)の場合：1.0以降に追加されたフィールドのみが出力されるため、lastName（2.0で追加）はJSONに含まれません。
• setVersion(2.0)の場合：2.0までのフィールドすべてが出力対象となるため、firstNameとlastNameの両方がJSONに含まれます。

この仕組みを活用することで、APIのバージョンアップなどでモデルクラスに新しいフィールドを追加した場合でも、古いクライアント向けには以前の形式のJSONを出力しつつ、新しいクライアント向けには拡張されたJSONを提供するといった互換性管理が容易になります。なお、逆に特定バージョン以降でフィールドを除外したい場合は、@Untilアノテーションを使用します。