Java 使用 Gson 解析 JSON 數據完整指南

前言

JSON 作為輕量級數據交換格式，已成為現代 Web 開發的標準。Google Gson 是 Java 生態中最流行的 JSON 庫之一，本文將通過實戰示例全面講解 Gson 的核心用法、進階技巧及常見坑點。

一、環境準備

Maven 依賴

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version> <!-- 請使用最新版本 -->
</dependency>

二、基礎用法：對象與 JSON 互轉

1. 定義實體類

public class User {
    private int id;
    private String name;
    private int age;
    
    // Getter/Setter 省略
    // 建議添加 @SerializedName 註解映射不同命名風格
    // @SerializedName("user_name")
    // private String name;
}

2. 基本序列化與反序列化

Gson gson = new Gson();

// 對象 → JSON
User user = new User(1, "Tom", 25);
String json = gson.toJson(user);
// {"id":1,"name":"Tom","age":25}

// JSON → 對象
String jsonStr = "{\"id\":2,\"name\":\"Marry\",\"age\":18}";
User user2 = gson.fromJson(jsonStr, User.class);

三、進階場景：泛型集合解析

TypeToken 解決類型擦除

import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.List;

String jsonArray = "[{\"id\":1,\"name\":\"Tom\"},{\"id\":2,\"name\":\"Marry\"}]";

// 錯誤寫法：List list = gson.fromJson(jsonArray, List.class);
// 正確寫法：
Type listType = new TypeToken<List<User>>(){}.getType();
List<User> userList = gson.fromJson(jsonArray, listType);

嵌套對象解析

public class Response<T> {
    private String message;
    private List<T> result;
    // getter/setter
}

// 解析
Type responseType = new TypeToken<Response<User>>(){}.getType();
Response<User> response = gson.fromJson(jsonStr, responseType);

四、Gson 核心配置優化

1. GsonBuilder 常用配置

Gson gson = new GsonBuilder()
    .setPrettyPrinting()                    // 格式化輸出
    .serializeNulls()                       // 序列化 null 字段
    .setDateFormat("yyyy-MM-dd HH:mm:ss")   // 統一日期格式
    .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES) // 駝峰轉下劃線
    .disableHtmlEscaping()                  // 禁用 HTML 轉義
    .create();

2. 自定義序列化/反序列化

// 適配器示例：處理特殊日期格式
Gson gson = new GsonBuilder()
    .registerTypeAdapter(LocalDateTime.class, new JsonDeserializer<LocalDateTime>() {
        @Override
        public LocalDateTime deserialize(JsonElement json, Type typeOfT, 
                                         JsonDeserializationContext context) 
                throws JsonParseException {
            return LocalDateTime.parse(json.getAsString(), 
                DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss"));
        }
    })
    .create();

五、常見問題與最佳實踐

1. 字段命名不一致

public class User {
    @SerializedName("user_id")
    private int id;
    
    @SerializedName("user_name") 
    private String name;
}

2. null 值處理

• 默認不序列化 null 字段
• 使用 `.serializeNulls()` 強制輸出 null
• 反序列化時缺失字段默認為 null

3. 日期類型處理

// 方式1：全局格式
Gson gson = new GsonBuilder().setDateFormat("yyyy-MM-dd").create();

// 方式2：字段級別註解
public class Event {
    @JsonAdapter(LocalDateTimeAdapter.class)
    private LocalDateTime createTime;
}

4. 泛型擦除陷阱

❌ 錯誤：`gson.fromJson(json, Map.class)` → Map<String, String> 但值實為 LinkedTreeMap
✅ 正確：使用 TypeToken 保留完整泛型信息

5. 性能優化建議

• 復用 Gson 實例（線程安全）
• 避免頻繁創建 TypeToken 匿名類
• 大數據量考慮流式解析 JsonReader/JsonWriter
• 關閉不需要的功能（如 HTML 轉義）

六、Gson vs Jackson vs json-org 對比

七、完整實戰示例

public class GsonDemo {
    public static void main(String[] args) {
        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        
        // 複雜對象構建
        Department dept = new Department("技術部");
        dept.addMember(new User(1, "Alice", 28));
        dept.addMember(new User(2, "Bob", 32));
        
        // 序列化
        String json = gson.toJson(dept);
        System.out.println("序列化結果：\n" + json);
        
        // 反序列化
        Type deptType = new TypeToken<Department>(){}.getType();
        Department dept2 = gson.fromJson(json, deptType);
        System.out.println("反序列化驗證：" + dept2.getName() + " - " + dept2.getMembers().size());
    }
}

總結

Gson 以簡潔的 API、優秀的易用性成為 Java JSON 處理首選。掌握 TypeToken 處理泛型、GsonBuilder 定制化配置、自定義適配器等進階技巧，能應對 95% 以上的業務場景。對於極致性能要求場景，可考慮 Jackson；Android 開發首選 Gson。