1. 概述
Gson 是 Google 提供的一个 Java 库，用于在 Java 对象与 JSON 字符串之间进行双向转换。简单来说：
✅ 可以把 Java 对象序列化成 JSON 字符串
✅ 也可以把 JSON 字符串反序列化为对应的 Java 对象
本文聚焦于前者：如何将各种 Java 数据类型序列化并写入 JSON 文件。内容简洁实用，适合快速查阅和踩坑参考。
2. Maven 依赖
要使用 Gson，首先在 pom.xml 中添加依赖。该库已发布在 Maven Central，直接引入即可：
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.10.1</version>
</dependency>
⚠️ 建议使用较新版本（如 2.10+），避免旧版本中存在的一些安全漏洞或功能限制。
3. 将数据写入 JSON 文件
Gson 提供了 toJson(Object src, Appendable writer) 方法，可直接将 Java 对象转换为 JSON 并输出到任意 Appendable 实例（比如文件流）。
创建 Gson 实例最简单的方式是：
Gson gson = new Gson();
这会使用默认配置。接下来就可以调用 gson.toJson() 方法完成序列化并写入文件。
下面通过几个典型场景演示用法。
3.1 基本数据类型
处理 int、double、String 等基本类型或包装类时，Gson 支持直接写入：
gson.toJson(123.45, new FileWriter("data.json"));
生成的 data.json 内容为：
123.45
✅ 是的，没有键值对，就是一个裸的数值 —— 这完全合法的 JSON。
同理，写入字符串：
gson.toJson("Hello World", new FileWriter("data.json"));
输出：
"Hello World"
简单粗暴，适合写配置、常量等场景。
3.2 自定义对象
这才是日常开发中最常见的需求。我们先定义一个 User 类：
public class User {
private int id;
private String name;
private transient String nationality;
public User(int id, String name, String nationality) {
this.id = id;
this.name = name;
this.nationality = nationality;
}
public User(int id, String name) {
this(id, name, null);
}
}
然后序列化一个实例：
User user = new User(1, "Tom Smith", "American");
gson.toJson(user, new FileWriter("user.json"));
生成的 JSON 文件内容为：
{"id":1,"name":"Tom"}
注意到两个细节：
- ❌
nationality字段没有出现 → 因为它被标记为transient，Gson 默认跳过此类字段 - ❌
name值是"Tom"而不是"Tom Smith"→ 构造器中传入的全名被截断？等等，不对！
⚠️ 等等！这里原文有误：
name实际应为"Tom Smith"。但根据输出{"id":1,"name":"Tom"}推测，可能是作者笔误或测试时用了不同构造方式。
实际上，Gson 会原样序列化字段值，不会自动截断。我们以代码逻辑为准。
更合理的解释是：作者可能想表达的是，如果传入 null 值，字段会被省略。比如：
gson.toJson(new User(1, null, "Unknown"), new FileWriter("user.json"));
输出：
{"id":1}
✅ 默认行为：Gson 在序列化时自动忽略值为 null 的字段
这是很多新手踩坑的地方 —— 以为字段“消失”了，其实是默认设置如此。
3.3 集合类型
Gson 对数组、List、Map 等集合支持良好。例如保存多个用户：
User[] users = new User[] {
new User(1, "Mike"),
new User(2, "Tom")
};
gson.toJson(users, new FileWriter("users.json"));
输出：
[{"id":1,"name":"Mike"},{"id":2,"name":"Tom"}]
✅ 完美生成 JSON 数组，无需额外操作。
对于 List<User> 也一样适用，只要传入正确类型即可。
4. 使用 GsonBuilder 自定义配置
上面的例子都基于默认配置。但在实际项目中，往往需要调整行为。这时就要用到 GsonBuilder。
它采用经典的建造者模式，链式设置选项，最后调用 .create() 生成 Gson 实例。
常见配置示例：
Gson gson = new GsonBuilder()
.setPrettyPrinting() // 格式化输出（带缩进）
.serializeNulls() // 保留 null 字段
.create();
应用后再次序列化 new User(1, null, "X")：
{
"id": 1,
"name": null
}
其他常用配置包括：
| 方法 | 作用 |
|---|---|
.excludeFieldsWithModifiers(Modifier.TRANSIENT) |
控制哪些修饰符字段被排除（默认已包含 transient） |
.setDateFormat("yyyy-MM-dd HH:mm:ss") |
自定义日期格式 |
.disableHtmlEscaping() |
禁用 HTML 转义（如保留 / 而非 \/） |
✅ 建议：在项目启动时统一构建一个全局 Gson 实例，避免重复创建影响性能。
5. 总结
本文演示了如何使用 Gson 将 Java 数据写入 JSON 文件，涵盖：
- ✅ 基本类型、自定义对象、集合的序列化
- ✅
transient字段和null值的默认处理机制 - ✅ 使用
GsonBuilder定制输出行为（如美化格式、保留 null）
📌 核心要点回顾：
gson.toJson(obj, FileWriter)可直接写文件- 默认不输出
null和transient字段 - 生产环境建议使用
GsonBuilder显式配置 - 多集合类型支持开箱即用
完整示例代码可在以下仓库找到：
👉 https://github.com/eugenp/tutorials/tree/master/json-modules/gson
作者邮箱：eugen@baeldung.com（用于联系原作者获取授权或反馈问题）