ZetCode

Gson

最后修改于 2024 年 10 月 10 日

Gson 教程展示了如何使用 Gson 库在 Java 中处理 JSON。 我们使用三种不同的 Gson API 来处理 JSON。 源代码可在作者的 Github repository 上找到。

JSON (JavaScript 对象表示法) 是一种轻量级的数据交换格式。 它易于人类阅读和编写，也易于机器解析和生成。 它比 XML 更简洁且更具可读性。 JSON 的官方 Internet 媒体类型是 application/json。 JSON 文件扩展名是 .json。 JSON 可以直接被 JavaScript 使用。

Gson 是一个 Java 序列化/反序列化库，用于将 Java 对象转换为 JSON 以及从 JSON 转换回 Java 对象。 Gson 由 Google 创建，供内部使用，后来开源。

Gson Maven 依赖

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

这是 Gson 的 Maven 依赖项。

Gson 功能

以下是 Gson 的功能

Gson API

Gson 有三种类型的 API

数据绑定 API 使用属性访问器在 JSON 和 POJO 之间进行转换。 Gson 使用数据类型适配器处理 JSON 数据。 它类似于 XML JAXB 解析器。

树模型 API 创建 JSON 文档的内存树表示。 它构建一个 JsonElements 树。 它类似于 XML DOM 解析器。

流式 API 是一个低级 API，它使用 JsonReader 和 JsonWriter 将 JSON 内容作为离散令牌读取和写入。 这些类将数据读取为 JsonTokens。 此 API 开销最低，并且在读/写操作中速度很快。 它类似于 XML 的 Stax 解析器。

Java Gson 类

Gson 是使用 Gson 库的主类。 有两种基本方法来创建 Gson

GsonBuilder 可用于构建具有各种配置设置的 Gson。

toJson 方法

toJson 方法将指定的对象序列化为其等效的 JSON 表示形式。

Main.java 
import com.google.gson.Gson;
import java.util.HashMap;
import java.util.Map;

void main() {

    Map<Integer, String> colours = new HashMap<>();
    colours.put(1, "blue");
    colours.put(2, "yellow");
    colours.put(3, "green");

    Gson gson = new Gson();

    String output = gson.toJson(colours);

    System.out.println(output);
}

在该示例中，我们使用 toJSon 方法将 Map 序列化为 JSON。

fromJson 方法

fromJson 方法将指定的 JSON 反序列化为指定类的对象。

Main.java 
import com.google.gson.Gson;

void main() {
    
    String json_string = """
            {"firstName":"Tom", "lastName": "Broody"}""";

    Gson gson = new Gson();
    User user = gson.fromJson(json_string, User.class);

    System.out.println(user);
}


record User(String firstName, String lastName) {
}

该示例使用 fromJson 方法将 JSON 读取到 Java 对象中。

GsonBuilder

GsonBuilder 构建具有各种配置设置的 Gson。 GsonBuilder 遵循构建器模式，它通常通过首先调用各种配置方法来设置所需的选项，最后调用 create 来使用。

Main.java 
import com.google.gson.FieldNamingPolicy;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

import java.io.PrintStream;
import java.nio.charset.StandardCharsets;

void main() {

    try (var prs = new PrintStream(System.out, true,
            StandardCharsets.UTF_8)) {

        Gson gson = new GsonBuilder()
                .setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE)
                .create();

        User user = new User("Peter", "Flemming");
        gson.toJson(user, prs);
    }
}

record User(String firstName, String lastName) {
}

在该示例中，我们将对象写入 JSON。 我们使用 GsonBuilder 来创建 Gson。

Gson gson = new GsonBuilder()
        .setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE)
        .create();

我们使用 GsonBuilder 创建和配置 Gson。 字段命名策略设置为 FieldNamingPolicy.UPPER_CAMEL_CASE。

Gson 格式化打印

Gson 有两种输出模式：紧凑模式和美化模式。

Main.java 
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import java.util.HashMap;
import java.util.Map;

void main() {

    Gson gson = new GsonBuilder().setPrettyPrinting().create();

    Map<String, Integer> items = new HashMap<>();

    items.put("chair", 3);
    items.put("pencil", 1);
    items.put("book", 5);

    gson.toJson(items, System.out);
}

该示例对 JSON 输出进行美化打印。

Gson gson = new GsonBuilder().setPrettyPrinting().create();

setPrettyPrinting 方法设置美化打印模式。

{
  "chair": 3,
  "book": 5,
  "pencil": 1
}

序列化空值

默认情况下，Gson 不会将具有空值的字段序列化为 JSON。 如果 Java 对象中的字段为 null，则 Gson 会将其排除。 我们可以通过使用 serializeNulls 方法，强制 Gson 通过 GsonBuilder 序列化 null 值。

Main.java 
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

class User {

    private String firstName;
    private String lastName;

    public User() {};

    public User(String firstName, String lastName) {
        this.firstName = firstName;
        this.lastName = lastName;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    @Override
    public String toString() {
        return new StringBuilder().append("User{").append("First name: ")
                .append(firstName).append(", Last name: ")
                .append(lastName).append("}").toString();
    }
}

void main() {

    GsonBuilder builder = new GsonBuilder();

    builder.serializeNulls();

    Gson gson = builder.create();

    User user = new User();
    user.setFirstName("Norman");

    String json = gson.toJson(user);
    System.out.println(json);

}

该示例演示了如何序列化 null 值。

{"firstName":"Norman","lastName":null}

Java Gson 写入列表

以下示例将 JSON 对象列表写入文件。

Main.java 
import com.google.gson.Gson;

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;


void main() throws IOException {

    String fileName = "src/main/resources/items.json";

    try (FileOutputStream fos = new FileOutputStream(fileName);
         OutputStreamWriter isr = new OutputStreamWriter(fos, StandardCharsets.UTF_8)) {

        Gson gson = new Gson();

        Item item1 = new Item("chair", 4);
        Item item2 = new Item("book", 5);
        Item item3 = new Item("pencil", 1);

        List<Item> items = new ArrayList<>();
        items.add(item1);
        items.add(item2);
        items.add(item3);

        gson.toJson(items, isr);
    }

    System.out.println("Items written to file");
}

record Item(String name, int quantity) {
}

该示例将 JSON 数据写入 items.json 文件。

Java Gson 读取到数组

下一个示例将数据读取到 Java 数组中。

$ cat users.json
[{"firstName":"Peter","lastName":"Flemming"}, {"firstName":"Nicole","lastName":"White"},
     {"firstName":"Robin","lastName":"Bullock"} ]

以下是 users.json 文件的内容。

Main.java 
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import java.io.File;
import java.io.IOException;
import java.io.Reader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Arrays;

void main() throws IOException {

    Gson gson = new GsonBuilder().create();

    String fileName = "src/main/resources/users.json";
    Path path = new File(fileName).toPath();

    try (Reader reader = Files.newBufferedReader(path,
            StandardCharsets.UTF_8)) {

        User[] users = gson.fromJson(reader, User[].class);

        Arrays.stream(users).forEach(System.out::println);
    }
}

record User(String firstName, String lastName) {
}

该示例将数据从 items.json 文件读取到数组中。 我们将数组的内容打印到控制台。

User[] users = gson.fromJson(reader, User[].class);

fromJson 的第二个参数是一个数组类。

Java Gson 从 URL 读取 JSON

以下示例从网页读取 JSON 数据。 我们从 http://time.jsontest.com 获取 JSON 数据。

{
    "date": "10-09-2024",
    "milliseconds_since_epoch": 1728466050756,
    "time": "09:27:30 AM"
}

GET 请求返回此 JSON 字符串。

Main.java 
import com.google.gson.Gson;

import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.net.URI;
import java.nio.charset.StandardCharsets;


void main() throws IOException {

    String webPage = "http://time.jsontest.com";

    try (InputStream is = URI.create(webPage).toURL().openStream();
         Reader reader = new InputStreamReader(is, StandardCharsets.UTF_8)) {

        Gson gson = new Gson();
        TimeData td = gson.fromJson(reader, TimeData.class);

        System.out.println(td);
    }
}

record TimeData(String time, Long milliseconds_since_epoch, String date) {}

代码示例从 http://time.jsontest.com 读取 JSON 数据。

TimeData[time=09:31:21 AM, milliseconds_since_epoch=1728466281476, date=10-09-2024]

Java Gson 使用 @Expose 排除字段

@Expose 注解指示应公开成员以进行 JSON 序列化或反序列化。 @Expose 注解可以采用两个布尔参数：serialize 和 deserialize。 必须使用 excludeFieldsWithoutExposeAnnotation 方法显式启用 @Expose 注解。

Main.java 
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.annotations.Expose;

enum MaritalStatus {

    SINGLE,
    MARRIED,
    DIVORCED,
    UNKNOWN
}

record Person(@Expose String firstName, @Expose String lastName,
              MaritalStatus maritalStatus) {
}


void main() {

    Gson gson = new GsonBuilder()
            .excludeFieldsWithoutExposeAnnotation()
            .setPrettyPrinting()
            .create();

    Person p = new Person("Jack", "Sparrow",
            MaritalStatus.UNKNOWN);

    String json = gson.toJson(p);
    System.out.println(json);
}

在该示例中，我们从序列化中排除一个字段。

record Person(@Expose String firstName, @Expose String lastName,
    MaritalStatus maritalStatus) {

婚姻状况字段将不会被序列化，因为它没有使用 @Expose 注解进行修饰。

Gson gson = new GsonBuilder()
        .excludeFieldsWithoutExposeAnnotation()
        .setPrettyPrinting()
        .create();

通过 @Expose 注解排除字段是通过 excludeFieldsWithoutExposeAnnotation 方法启用的。

{
  "firstName": "Jack",
  "lastName": "Sparrow"
}

数据绑定 API

数据绑定 API 使用属性访问器在 JSON 和 POJO 之间进行转换。 Gson 使用数据类型适配器处理 JSON 数据。

数据绑定 API 写入

在以下示例中，我们使用数据绑定 API 写入数据。

Main.java 
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

import java.io.IOException;
import java.io.Writer;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

void main() throws IOException {

    List<Car> cars = new ArrayList<>();
    cars.add(new Car("Audi", "2012", 22000, new String[]{"gray", "red", "white"}));
    cars.add(new Car("Skoda", "2016", 14000, new String[]{"black", "gray", "white"}));
    cars.add(new Car("Volvo", "2010", 19500, new String[]{"black", "silver", "beige"}));

    String fileName = "src/main/resources/cars.json";
    Path path = Paths.get(fileName);

    try (Writer writer = Files.newBufferedWriter(path, StandardCharsets.UTF_8)) {

        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        gson.toJson(cars, writer);
    }

    System.out.println("Cars written to file");
}

record Car(String name, String model, int price, String[] colours) {
}

在该示例中，我们创建一个 car 对象列表，并使用 Gson 数据绑定 API 将其序列化。

Gson gson = new GsonBuilder().setPrettyPrinting().create();
gson.toJson(cars, writer);

我们将 cars 列表传递给 toJson 方法。 Gson 会自动将 car 对象映射到 JSON。

Gson 数据绑定 API 读取

在以下示例中，我们使用数据绑定 API 读取数据。

Main.java 
import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;

import java.io.IOException;
import java.io.Reader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;


void main() throws IOException {

    String fileName = "src/main/resources/cars.json";
    Path path = Paths.get(fileName);

    try (Reader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8)) {

        Gson gson = new Gson();
        List<Car> cars = gson.fromJson(reader, new TypeToken<List<Car>>() {
        }.getType());

        cars.forEach(System.out::println);
    }
}

record Car(String name, String model, int price, String[] colours) {
}

在该示例中，我们使用 Gson 数据绑定 API 从 JSON 文件读取数据到 car 对象列表中。

List<Car> cars = gson.fromJson(reader, new TypeToken<List<Car>>() {
    }.getType());

Gson 自动将 JSON 映射到 Car 对象。 由于类型信息在运行时丢失，因此我们需要使用 TypeToken 让 Gson 知道我们使用的类型。

Java Gson 树模型 API

树模型 API 在内存中创建 JSON 文档的树表示。 它构建一个 JsonElements 树。 JsonElement 是表示 Json 元素的类。 它可以是 JsonObject、JsonArray、JsonPrimitive 或 JsonNull。

Gson 树模型写入

在以下示例中，我们使用 Gson 树模型 API 将 Java 对象写入 JSON。

Main.java 
import com.google.gson.Gson;
import com.google.gson.JsonElement;

import java.io.IOException;
import java.io.Writer;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;


void main() throws IOException {

    List<Car> cars = new ArrayList<>();
    cars.add(new Car("Audi", "2012", 22000,
            new String[]{"gray", "red", "white"}));
    cars.add(new Car("Skoda", "2016", 14000,
            new String[]{"black", "gray", "white"}));
    cars.add(new Car("Volvo", "2010", 19500,
            new String[]{"black", "silver", "beige"}));

    String fileName = "src/main/resources/cars.json";
    Path path = Paths.get(fileName);

    try (Writer writer = Files.newBufferedWriter(path, StandardCharsets.UTF_8)) {

        Gson gson = new Gson();

        JsonElement tree = gson.toJsonTree(cars);
        gson.toJson(tree, writer);
    }

    System.out.println("Cars written to file");
}

record Car(String name, String model, int price, String[] colours) {
}

car 对象列表被序列化为 JSON 格式。

JsonElement tree = gson.toJsonTree(cars);

toJsonTree 方法将指定的对象序列化为其等效的 JsonElements 树的表示形式。

Gson 树模型读取

在以下示例中，我们使用 Gson 树模型 API 从 JSON 读取 Java 对象。

cars.json 
[{"name":"Audi","model":"2012","price":22000,"colours":["gray","red","white"]},
 {"name":"Skoda","model":"2009","price":14000,"colours":["black","gray","white"]},
 {"name":"Volvo","model":"2010","price":19500,"colours":["black","silver","beige"]}]

这是 cars.json 文件中的 JSON 数据。

Main.java 
import com.google.gson.JsonArray;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

import java.io.IOException;
import java.io.Reader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;


void main() throws IOException {

    String fileName = "src/main/resources/cars.json";
    Path path = Paths.get(fileName);

    try (Reader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8)) {

        JsonElement tree = JsonParser.parseReader(reader);
        JsonArray array = tree.getAsJsonArray();

        for (JsonElement element : array) {

            if (element.isJsonObject()) {

                JsonObject car = element.getAsJsonObject();

                System.out.println("********************");
                System.out.println(car.get("name").getAsString());
                System.out.println(car.get("model").getAsString());
                System.out.println(car.get("price").getAsInt());

                JsonArray cols = car.getAsJsonArray("colours");

                cols.forEach(System.out::println);
            }
        }
    }
}

在该示例中，我们将 JSON 数据从文件读取到 JsonElements 树中。

JsonElement tree = JsonParser.parseReader(reader);

JsonParser 将 JSON 解析为 JsonElements 的树结构。

JsonArray array = tree.getAsJsonArray();

我们获取作为 JsonArray 的树。

for (JsonElement element : array) {

    if (element.isJsonObject()) {

        JsonObject car = element.getAsJsonObject();

        System.out.println("********************");
        System.out.println(car.get("name").getAsString());
        System.out.println(car.get("model").getAsString());
        System.out.println(car.get("price").getAsInt());

        JsonArray cols = car.getAsJsonArray("colours");

        cols.forEach(System.out::println);
    }
}

我们遍历 JsonArray 并打印其元素的内容。

Java Gson 流式 API

Gson 流式 API 是一个低级 API，它将 JSON 作为离散令牌 (JsonTokens) 读取和写入。 主要类是 JsonReader 和 JsonWriter。 JsonToken 是 JSON 编码字符串中的结构、名称或值类型。

以下是 JsonToken 类型

Gson JsonWriter

JsonWriter 一次将一个 JSON 编码值写入流。 该流包括文字值（字符串、数字、布尔值和 null 值）以及对象和数组的开始和结束分隔符。 每个 JSON 文档都必须包含一个顶级数组或对象。

对象是使用 beginObject 和 endObject 方法调用创建的。 在对象中，令牌在名称及其值之间交替。 数组是在 beginArray 和 endArray 方法调用中创建的。

Main.java 
import com.google.gson.stream.JsonWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;


void main() throws IOException {

    String fileName = "src/main/resources/cars.json";
    Path path = Paths.get(fileName);

    try (JsonWriter writer = new JsonWriter(Files.newBufferedWriter(path,
            StandardCharsets.UTF_8))) {

        writer.beginObject();
        writer.name("name").value("Audi");
        writer.name("model").value("2012");
        writer.name("price").value(22000);

        writer.name("colours");
        writer.beginArray();
        writer.value("gray");
        writer.value("red");
        writer.value("white");
        writer.endArray();

        writer.endObject();
    }

    System.out.println("Data written to file");
}

在该示例中，我们将一个 car 对象写入 JSON 文件。

try (JsonWriter writer = new JsonWriter(Files.newBufferedWriter(path,
        StandardCharsets.UTF_8))) {

创建一个新的 JsonWriter。

writer.beginObject();
...
writer.endObject();

正如我们上面所说的，每个 JSON 文档都必须有一个顶级数组或对象。 在我们的例子中，我们有一个顶级对象。

writer.name("name").value("Audi");
writer.name("model").value("2012");
writer.name("price").value(22000);

我们将键值对写入文档。

writer.name("colours");
writer.beginArray();
writer.value("gray");
writer.value("red");
writer.value("white");
writer.endArray();

在这里我们创建一个数组。

Gson JsonReader

JsonReader 将 JSON 编码的值读取为令牌流。

Main.java 
import com.google.gson.stream.JsonReader;
import com.google.gson.stream.JsonToken;

import java.io.IOException;
import java.io.StringReader;


void main() throws IOException {

    String json_string = """
            {"name":"chair","quantity":3}""";

    try (JsonReader reader = new JsonReader(new StringReader(json_string))) {

        while (reader.hasNext()) {

            JsonToken nextToken = reader.peek();

            if (JsonToken.BEGIN_OBJECT.equals(nextToken)) {

                reader.beginObject();

            } else if (JsonToken.NAME.equals(nextToken)) {

                reader.nextName();

            } else if (JsonToken.STRING.equals(nextToken)) {

                String value = reader.nextString();
                System.out.format("%s: ", value);

            } else if (JsonToken.NUMBER.equals(nextToken)) {

                long value = reader.nextLong();
                System.out.println(value);

            }
        }
    }
}

该示例使用 JsonReader 从 JSON 字符串读取数据。

JsonReader reader = new JsonReader(new StringReader(json_string));

创建 JsonReader 对象。 它从 JSON 字符串读取数据。

while (reader.hasNext()) {

在 while 循环中，我们迭代流中的令牌。

JsonToken nextToken = reader.peek();

我们使用 peek 方法获取下一个令牌的类型。

reader.beginObject();

beginObject 方法从 JSON 流中使用下一个令牌，并断言它是新对象的开头。

reader.nextName();

nextName 方法返回下一个 JsonToken 并使用它。

String value = reader.nextString();
System.out.format("%s: ", value);

我们获取下一个字符串值并将其打印到控制台。

来源

Gson Github 页面

在本文中，我们展示了如何使用 Gson 库来处理 JSON。

作者

我叫 Jan Bodnar，是一位充满激情的程序员，拥有丰富的编程经验。 我从 2007 年开始撰写编程文章。到目前为止，我已经撰写了 1,400 多篇文章和 8 本电子书。 我拥有超过十年的编程教学经验。

列出所有Java教程。