Gson处理动态JSON结构：灵活解析单对象与对象列表

本文探讨了在使用Gson解析JSON时，如何应对同一字段有时为单个JSON对象、有时为JSON对象列表的动态结构问题。通过自定义TypeAdapterFactory并结合@JsonAdapter注解，我们能够实现灵活的类型适配，确保无论是单对象还是列表，都能被正确地反序列化为预期的Java集合类型，从而提高JSON解析的健壮性。

1. 问题背景与挑战

在与第三方api交互时，我们经常会遇到json数据结构不一致的情况。一个常见的场景是，某个字段在某些情况下表示一个单独的json对象，而在另一些情况下则表示一个json对象数组。例如，以下两种json结构都可能出现在同一个api响应中：

情况一：RadarReport 为单个对象

{
  "RadarReports": {
    "executionTime": "135",
    "RadarReport": {
      "abc": "1116591",
      "name": "abc",
      "id": "2019050311582056119",
      "ownerId": "xyz"
    },
    "size": "1"
  }
}

情况二：RadarReport 为对象列表

{
  "RadarReports": {
    "executionTime": "113",
    "RadarReport": [
      {
        "abc": "1116591",
        "name": "abc",
        "id": "2019050311582056119",
        "ownerId": "xyz"
      },
      {
        "abc": "1116591",
        "name": "abc",
        "id": "2019050311582056119",
        "ownerId"
: "xyz"
      }
    ],
    "size": "2"
  }
}

如果直接使用Gson将RadarReport字段映射到ArrayList，当遇到单个对象的情况时，Gson会抛出类型不匹配的异常，因为期望的是一个数组开始符[而不是一个对象开始符{。

2. 解决方案：自定义TypeAdapterFactory

为了优雅地处理这种动态类型，Gson提供了TypeAdapterFactory接口。通过实现自定义的TypeAdapterFactory，我们可以在Gson进行反序列化之前，检查JSON流的当前令牌类型，并根据类型执行不同的处理逻辑。

核心思路是：当RadarReport字段是单个JSON对象时，我们将其包装成一个临时的JSON数组，然后再交由Gson的默认列表适配器进行反序列化。

2.1 创建自定义TypeAdapterFactory

import com.google.gson.Gson;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import com.google.gson.TypeAdapter;
import com.google.gson.TypeAdapterFactory;
import com.google.gson.reflect.TypeToken;
import com.google.gson.stream.JsonReader;
import com.google.gson.stream.JsonToken;
import com.google.gson.stream.JsonWriter;

import java.io.IOException;
import java.util.ArrayList; // 假设RadarReport最终会映射到ArrayList

// 此工厂旨在与 @JsonAdapter 注解配合使用
class SingleObjectOrListAdapterFactory implements TypeAdapterFactory {

    @Override
    public  TypeAdapter create(Gson gson, TypeToken type) {
        // 获取目标类型（例如 ArrayList）的默认适配器
        // 注意：这里直接使用 gson.getAdapter(type) 是获取泛型类型适配器的正确方式
        final TypeAdapter listAdapterDelegate = gson.getAdapter(type);

        // 获取 JsonObject 类型的适配器，用于读取单个对象
        final TypeAdapter jsonObjectAdapter = gson.getAdapter(JsonObject.class);

        // 返回一个自定义的TypeAdapter
        return new TypeAdapter() {
            @Override
            public void write(JsonWriter out, T value) throws IOException {
                // 写入逻辑通常直接委托给默认适配器
                listAdapterDelegate.write(out, value);
            }

            @Override
            public T read(JsonReader in) throws IOException {
                // 关键的读取逻辑：根据当前JSON令牌类型进行判断
                if (in.peek() == JsonToken.BEGIN_OBJECT) {
                    // 如果当前令牌是对象开始符（{），说明是单个对象
                    // 1. 读取整个JSON对象
                    JsonObject jsonObject = jsonObjectAdapter.read(in);
                    // 2. 创建一个JSON数组
                    JsonArray jsonArray = new JsonArray();
                    // 3. 将读取到的单个对象添加到数组中
                    jsonArray.add(jsonObject);
                    // 4. 将这个包装后的JSON数组转换为目标类型（例如 ArrayList）
                    return listAdapterDelegate.fromJsonTree(jsonArray);
                } else {
                    // 如果当前令牌是数组开始符（[），或者其他预期的令牌（如NULL），
                    // 直接委托给默认的列表适配器进行处理
                    return listAdapterDelegate.read(in);
                }
            }
        };
    }
}

2.2 POJO定义

首先，定义RadarReport类来映射单个报告对象：

import lombok.Data; // 假设使用Lombok简化POJO

@Data
public class RadarReport {
    private String abc;
    private String name;
    private String id;
    private String ownerId;
}

然后，在包含RadarReport列表的父类Radarreports中，使用@JsonAdapter注解将自定义的TypeAdapterFactory应用于RadarReport字段：

import lombok.Data;
import com.google.gson.annotations.JsonAdapter;
import java.util.ArrayList;

@Data
public class Radarreports {
    private int size;
    // 使用 @JsonAdapter 指定自定义的 TypeAdapterFactory
    @JsonAdapter(SingleObjectOrListAdapterFactory.class)
    private ArrayList RadarReport; // 注意字段名与JSON保持一致
    // private ArrayList RadarReportSet; // 如果存在，也需要根据实际情况处理
    private String executionTime; // 添加这个字段以完整映射示例JSON
}

最后，定义顶层响应类ReportsResponse：

import lombok.Data;

@Data
public class ReportsResponse {
    private Radarreports RadarReports;
}

3. 使用示例

在Java应用程序中，使用Gson进行反序列化时，只需像往常一样创建Gson实例并调用fromJson方法：

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;

public class JsonParsingExample {

    public static void main(String[] args) {
        // 模拟两种JSON输入
        String jsonSingleObject = "{\"RadarReports\": {\"executionTime\": \"135\",\"RadarReport\": {\"abc\": \"1116591\",\"name\": \"abc\",\"id\": \"2019050311582056119\",\"ownerId\": \"xyz\"},\"size\" :\"1\"}}";
        String jsonArrayOfObjects = "{\"RadarReports\": {\"executionTime\": \"113\",\"RadarReport\": [{\"abc\": \"1116591\",\"name\": \"abc\",\"id\": \"2019050311582056119\",\"ownerId\": \"xyz\"},{\"abc\": \"1116591\",\"name\": \"abc\",\"id\": \"2019050311582056119\",\"ownerId\": \"xyz\"}],\"size\" : \"2\"}}";

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

        // 测试单对象情况
        try {
            ReportsResponse responseSingle = gson.fromJson(jsonSingleObject, ReportsResponse.class);
            System.out.println("--- 解析单对象JSON ---");
            System.out.println("Execution Time: " + responseSingle.getRadarReports().getExecutionTime());
            System.out.println("Size: " + responseSingle.getRadarReports().getSize());
            System.out.println("RadarReport Count: " + responseSingle.getRadarReports().getRadarReport().size());
            responseSingle.getRadarReports().getRadarReport().forEach(report ->
                System.out.println("  ID: " + report.getId() + ", Name: " + report.getName())
            );
        } catch (Exception e) {
            System.err.println("解析单对象JSON失败: " + e.getMessage());
            e.printStackTrace();
        }

        System.out.println("\n---------------------------\n");

        // 测试列表对象情况
        try {
            ReportsResponse responseArray = gson.fromJson(jsonArrayOfObjects, ReportsResponse.class);
            System.out.println("--- 解析列表JSON ---");
            System.out.println("Execution Time: " + responseArray.getRadarReports().getExecutionTime());
            System.out.println("Size: " + responseArray.getRadarReports().getSize());
            System.out.println("RadarReport Count: " + responseArray.getRadarReports().getRadarReport().size());
            responseArray.getRadarReports().getRadarReport().forEach(report ->
                System.out.println("  ID: " + report.getId() + ", Name: " + report.getName())
            );
        } catch (Exception e) {
            System.err.println("解析列表JSON失败: " + e.getMessage());
            e.printStackTrace();
        }

        // 实际应用中可能通过URL读取
        // try {
        //     URL url = new URL(queryUrl);
        //     BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream()));
        //     ReportsResponse radarReports = gson.fromJson(br, ReportsResponse.class);
        //     // ... 处理 radarReports 对象
        // } catch (Exception e) {
        //     e.printStackTrace();
        // }
    }
}

4. 注意事项与总结

• TypeAdapterFactory的强大之处：TypeAdapterFactory是Gson中处理复杂或动态类型映射的强大机制。它允许你在Gson创建任何特定类型的TypeAdapter之前，插入自己的逻辑来决定如何处理该类型。
• @JsonAdapter注解：通过在POJO字段上使用@JsonAdapter(YourTypeAdapterFactory.class)，你可以指定Gson在反序列化该字段时使用你自定义的适配器。这使得解决方案非常局部化和模块化。
• 错误处理：在实际应用中，read方法内部应考虑更全面的错误处理，例如当in.peek()返回意外的JsonToken时。
• 性能考量：虽然自定义适配器增加了少量开销，但对于大多数应用场景来说，这种开销是微不足道的，尤其是在解决数据结构不一致问题时带来的健壮性提升。
• 写入操作：在write方法中，通常可以直接委托给默认适配器，除非你需要对序列化过程也进行特殊处理。

通过以上方法，我们成功地解决了Gson在解析动态JSON结构时遇到的挑战，使得程序能够健壮地处理来自第三方API的不确定数据格式。这种模式在处理遗留系统或设计不佳的API时尤其有用。