Google Gson 完整使用指南：從基礎序列化到進階類型適配器

Google Gson 完整使用指南：從基礎序列化到進階類型適配器

Gson 是 Google 開源的 Java JSON 庫，以 API 簡潔、效能優異、支援泛型與自定義類型適配聞名。本文提供 Maven/Gradle 依賴、核心 API、工具類封裝與常見坑點。

依賴配置

// Gradle
implementation 'com.google.code.gson:gson:2.10.1'

// Maven
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

核心 API 快速上手

Gson gson = new Gson();

// 物件 -> JSON
User user = new User("Alice", 25);
String json = gson.toJson(user); // {"name":"Alice","age":25}

// JSON -> 物件
User parsed = gson.fromJson(json, User.class);

// List -> JSON
List<User> users = Arrays.asList(new User("A",1), new User("B",2));
String listJson = gson.toJson(users);

// JSON -> List (需 TypeToken)
Type listType = new TypeToken<List<User>>(){}.getType();
List<User> parsedList = gson.fromJson(listJson, listType);

進階配置：GsonBuilder

Gson gson = new GsonBuilder()
    .setPrettyPrinting()                    // 格式化輸出
    .disableHtmlEscaping()                  // 不轉義 HTML 字元
    .serializeNulls()                       // 序列化 null 欄位
    .setDateFormat("yyyy-MM-dd HH:mm:ss")   // 統一日期格式
    .registerTypeAdapter(LocalDateTime.class, new LocalDateTimeAdapter()) // 自定義適配器
    .create();

實用工具類封裝 (含日期處理)

public class GsonUtils {
    private static final Gson GSON = new GsonBuilder()
        .disableHtmlEscaping()
        .registerTypeAdapter(Date.class, new DateSerializer())
        .registerTypeAdapter(Date.class, new DateDeserializer())
        .create();

    public static <T> T fromJson(String json, Class<T> clazz) {
        return GSON.fromJson(json, clazz);
    }

    public static <T> List<T> fromJsonList(String json, Class<T> clazz) {
        Type type = TypeToken.getParameterized(List.class, clazz).getType();
        return GSON.fromJson(json, type);
    }

    public static List<Map<String, Object>> fromJsonToListMap(String json) {
        return GSON.fromJson(json, new TypeToken<List<Map<String, Object>>>(){}.getType());
    }

    public static String toJson(Object obj) {
        return GSON.toJson(obj);
    }
}

常見坑點與解決方案

效能優化建議

• 單例複用 Gson 實例 (線程安全)
• 大量資料流式處理用 JsonReader/JsonWriter (SAX 風格)
• 避免頻繁建立 TypeToken 匿名類，提取為常量