Java JSON 庫 Gson 入門教程：核心 API、註解策略與字段過濾實戰

前言

Gson 是 Google 開源的 Java JSON 庫，以「零配置啟動、註解深度定制」著稱。本文從最基礎的 toJson/fromJson 入手，逐步講解 GsonBuilder 定制、@Expose 字段過濾、@SerializedName 字段重命名等核心技能，助你快速掌握 Gson 實戰精髓。

核心對象與方法

• Gson：主入口，線程安全，可復用。
• GsonBuilder：構建定制化 Gson 實例（格式化、空值、註解策略、日期格式等）。
• toJson(obj)：Java 對象 → JSON 字符串。
• fromJson(json, Type)：JSON 字符串 → Java 對象。

實體類定義

public class People {
    private String name;
    private int age;
    private boolean setName; // 字段名以 set 開頭，用於演示過濾
    // Getter/Setter/toString 省略
}

最簡單的序列化/反序列化

People p = new People(); p.setName("People"); p.setAge(20); p.setSetName(true);
Gson gson = new Gson();
String json = gson.toJson(p); // {"name":"People","age":20,"setName":true}
People p2 = gson.fromJson(json, People.class);

進階場景一：字段過濾 — ExclusionStrategy

需求： 序列化時忽略以 "set" 開頭的字段（如 setName）。

// 1. 實現策略接口
class SetterExclusionStrategy implements ExclusionStrategy {
    public boolean shouldSkipClass(Class clazz) { return false; }
    public boolean shouldSkipField(FieldAttributes f) { return f.getName().startsWith("set"); }
}

// 2. 構建帶策略的 Gson
Gson gsonFilter = new GsonBuilder()
    .setExclusionStrategies(new SetterExclusionStrategy())
    .create();

String jsonFiltered = gsonFilter.toJson(p); // {"name":"People","age":20}  無 setName
People pFiltered = gsonFilter.fromJson(jsonFiltered, People.class); // setName 為默認 false

• shouldSkipClass：控制整個類是否跳過。
• shouldSkipField：控制單字段是否跳過，可訪問字段名、註解、修飾符等元信息。
• 策略對序列化與反序列化雙向生效。

進階場景二：註解控制 — @Expose

需求： 精確控制哪些字段參與序列化/反序列化。

public class User {
    @Expose private String firstName;                    // 序列化 + 反序列化
    @Expose(serialize = false) private String lastName;  // 僅反序列化
    @Expose(deserialize = false) private String email;   // 僅序列化
    private String password;                             // 完全忽略
}

// 必須啟用註解策略
Gson gson = new GsonBuilder()
    .excludeFieldsWithoutExposeAnnotation() // 關鍵：未標註 @Expose 的字段全部忽略
    .create();

• 默認 new Gson() 會處理所有字段（含 private），@Expose 僅在配合 excludeFieldsWithoutExposeAnnotation() 時生效。
• 細粒度控制 serialize/deserialize 屬性，適配「寫入不讀出、讀出不寫入」場景。

進階場景三：字段重命名 — @SerializedName

需求： Java 字段駝峰命名，JSON 需下劃線或指定名稱。

public class SomeClass {
    @SerializedName("custom_naming") private String someField;
    private String someOtherField;
}

Gson gson = new Gson();
String json = gson.toJson(new SomeClass("a", "b"));
// {"custom_naming":"a","someOtherField":"b"}

• 覆蓋全局命名策略（FieldNamingPolicy）。
• 值必須是合法 JSON 字段名。

全局命名策略 — FieldNamingPolicy

Gson gson = new GsonBuilder()
    .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES) // 駝峰 → 下劃線
    .create();
// someField → some_field, someOtherField → some_other_field

內置策略：IDENTITY(保持原樣)、UPPER_CAMEL_CASE(首字母大寫駝峰)、LOWER_CASE_WITH_UNDERSCORES(下劃線)、UPPER_CASE_WITH_UNDERSCORES(大寫下劃線)。

版本控制 — @Since

public class VersionedClass {
    @Since(1.1) private String newerField;
    @Since(1.0) private String newField;
    private String field;
}
Gson gsonV1 = new GsonBuilder().setVersion(1.0).create(); // 僅輸出 newField, field
Gson gsonAll = new Gson(); // 輸出所有

總結

Gson 的設計哲學是「約定優於配置，配置優於代碼」。掌握 GsonBuilder 鏈式配置、ExclusionStrategy 程序化過濾、@Expose/@SerializedName/@Since 註解三板斧，即可優雅解決 99% 的 JSON 交互需求。建議專案封裝統一的 GsonProvider，集中管理實例與策略。