背景与挑战
在与外部系统集成时，我们经常需要解析由其提供的json数据。一个常见但棘手的问题是，同一个json字段在不同情况下可能具有不同的数据类型。例如，一个表示“报告列表”的字段，当只有一个报告时，它可能被表示为一个单独的json对象；而当有多个报告时，则被表示为一个json数组。
考虑以下两种来自第三方系统的JSON结构：
情况一：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"
}
}如果我们尝试使用标准的Java POJO（Plain Old Java Object）和Gson进行反序列化，并将RadarReport字段直接映射到ArrayList
Gson解决方案：自定义TypeAdapterFactory
为了优雅地解决这种动态类型映射问题，我们可以利用Gson提供的TypeAdapterFactory机制。TypeAdapterFactory允许我们注册自定义的类型适配器，在Gson进行序列化或反序列化时介入处理特定类型的数据。
核心思想是：在反序列化RadarReport字段时，首先检查其JSON令牌类型。如果是一个JSON对象（BEGIN_OBJECT），我们将其包装成一个单元素的JSON数组，然后再交由Gson的默认列表适配器进行处理；如果本身就是JSON数组（BEGIN_ARRAY），则直接进行处理。
以下是实现这一逻辑的SingleObjectOrListAdapterFactory：
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.annotations.JsonAdapter; // For annotation usage
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;
/**
* 自定义TypeAdapterFactory，用于处理JSON中单个对象或对象列表的动态映射。
* 当JSON字段为单个对象时，将其包装为数组再进行反序列化。
*/
class SingleObjectOrListAdapterFactory implements TypeAdapterFactory {
@Override
public TypeAdapter create(Gson gson, TypeToken type) {
// 确保此工厂只应用于ArrayList类型，或者更具体的类型，如ArrayList
// 这里我们假设它会应用于 @JsonAdapter 注解指定的类型
// listAdapterDelegate 是 Gson 针对目标类型（例如 ArrayList）的默认适配器
final TypeAdapter listAdapterDelegate = gson.getAdapter(type);
// jsonObjectAdapter 用于读取单个 JSON 对象
final TypeAdapter jsonObjectAdapter = gson.getAdapter(JsonObject.class);
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令牌类型进行判断
JsonToken peekedToken = in.peek();
if (peekedToken == JsonToken.BEGIN_OBJECT) {
// 如果当前令牌是 JSON 对象开始，说明是单个对象
// 1. 读取该 JSON 对象
JsonObject jsonObject = jsonObjectAdapter.read(in);
// 2. 将该 JSON 对象包装到一个新的 JSON 数组中
JsonArray jsonArray = new JsonArray();
jsonArray.add(jsonObject);
// 3. 使用默认的列表适配器从包装后的 JSON 树中反序列化
return listAdapterDelegate.fromJsonTree(jsonArray);
} else {
// 如果当前令牌是 JSON 数组开始，或者其他情况（如null），
// 直接使用默认的列表适配器进行读取
return listAdapterDelegate.read(in);
}
}
};
}
} POJO定义与@JsonAdapter注解
为了将上述自定义适配器应用到我们的Java对象模型中，我们需要在POJO的相应字段上使用@JsonAdapter注解。
首先，定义RadarReport类来表示单个报告的结构：
import lombok.Data;
@Data
public class RadarReport {
private String abc;
private String name;
private String id;
private String ownerId;
}然后，定义包含RadarReport列表的容器类。注意，RadarReport字段现在是一个ArrayList类型，并且应用了@JsonAdapter注解：
import lombok.Data;
import com.google.gson.annotations.JsonAdapter;
import java.util.ArrayList;
@Data
public class RadarReportsContainer { // 对应JSON中的 "RadarReports" 对象
private String executionTime;
private String size;
// 使用 @JsonAdapter 注解指定自定义的 TypeAdapterFactory
@JsonAdapter(SingleObjectOrListAdapterFactory.class)
private ArrayList RadarReport; // 字段类型为 ArrayList
} 最后，定义最外层的响应类：
import lombok.Data;
@Data
public class ReportsResponse { // 对应最外层 JSON 对象
private RadarReportsContainer RadarReports; // 字段名与JSON一致
}完整示例与使用
现在，我们可以使用配置好的Gson实例来解析上述两种JSON结构，无论RadarReport是单个对象还是数组，都将成功映射到ArrayList
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.ArrayList;
public class JsonParsingExample {
public static void main(String[] args) throws Exception {
// 模拟两种JSON输入
String jsonSingleObject = "{\"RadarReports\": {\"executionTime\": \"135\",\"RadarReport\": {\"abc\": \"1116591\",\"name\": \"abc\",\"id\": \"2019050311582056119\",\"ownerId\": \"xyz\"},\"size\" :\"1\"}}";
String jsonArrayObject = "{\"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(); // 无需额外注册，@JsonAdapter 会自动使用
// 解析单个对象的情况
System.out.println("--- 解析单个对象JSON ---");
ReportsResponse responseSingle = gson.fromJson(jsonSingleObject, ReportsResponse.class);
if (responseSingle != null && responseSingle.getRadarReports() != null) {
System.out.println("Execution Time: " + responseSingle.getRadarReports().getExecutionTime());
System.out.println("Size: " + responseSingle.getRadarReports().getSize());
if (responseSingle.getRadarReports().getRadarReport() != null) {
System.out.println("RadarReport List Size: " + responseSingle.getRadarReports().getRadarReport().size());
responseSingle.getRadarReports().getRadarReport().forEach(report -> System.out.println(" Report ID: " + report.getId()));
}
}
System.out.println("\n--- 解析数组对象JSON ---");
// 解析数组对象的情况
ReportsResponse responseArray = gson.fromJson(jsonArrayObject, ReportsResponse.class);
if (responseArray != null && responseArray.getRadarReports() != null) {
System.out.println("Execution Time: " + responseArray.getRadarReports().getExecutionTime());
System.out.println("Size: " + responseArray.getRadarReports().getSize());
if (responseArray.getRadarReports().getRadarReport() != null) {
System.out.println("RadarReport List Size: " + responseArray.getRadarReports().getRadarReport().size());
responseArray.getRadarReports().getRadarReport().forEach(report -> System.out.println(" Report ID: " + report.getId()));
}
}
// 实际从URL读取的示例（与原问题类似）
// String queryUrl = "http://your.api.endpoint/data";
// URL url = new URL(queryUrl);
// try (BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream()))) {
// ReportsResponse radarReports = gson.fromJson(br, ReportsResponse.class);
// // 处理 radarReports 对象
// System.out.println("\n--- 从URL解析 ---");
// if (radarReports != null && radarReports.getRadarReports() != null) {
// System.out.println("URL Data RadarReport List Size: " + radarReports.getRadarReports().getRadarReport().size());
// }
// }
}
}注意事项与最佳实践
- 适用场景： 这种自定义TypeAdapterFactory的方法特别适用于处理外部API返回的JSON结构不一致的情况，尤其是当一个字段可能表示单对象或对象数组时。
- 代码健壮性： 通过预判JSON令牌类型并进行适当的包装，极大地增强了JSON解析的健壮性，避免了因JSON结构变化而导致的运行时错误。
- 可维护性： 将复杂的解析逻辑封装在TypeAdapterFactory中，使得POJO定义保持简洁，提高了代码的可读性和可维护性。
- 性能考量： in.peek()操作本身开销很小。对于单对象情况，会额外执行一次JsonObject的读取和JsonArray的创建，但对于大多数应用场景而言，这种性能开销是微不足道的。
- 泛用性： SingleObjectOrListAdapterFactory的设计是通用的，可以应用于任何需要将单对象或对象列表统一映射到ArrayList的场景，只需在相应的POJO字段上使用@JsonAdapter注解即可。
- 错误处理： 在实际生产环境中，除了类型不匹配，还应考虑其他可能的JSON解析错误（如格式错误、网络问题等），并添加相应的异常处理机制。
通过上述方法，我们能够有效地利用Gson的强大扩展性，解决JSON数据结构动态变化的复杂问题，确保应用程序能够稳定、灵活地处理各种外部数据源。
