处理非标准JSON数组与Retrofit2：定制化POJO模型生成与反序列化

理解非标准JSON数据结构

我们所面临的JSON数据结构如下所示：

[
   [
      "S#",
      "Name of Minister",
      "Portfolio",
      "Contact #",
      "PRO Name",
      "PRO Contact",
      "PRO Contact #"
   ],
   [
      "1",
      "Mr. Mohammad Ali Saif",
      "Information and PRs",
      "9212894",
      "Mr. Rizwan Malik",
      "0345-",
      ""
   ],
   [
      "2",
      "Mr. Abdul Karim",
      "Industries",
      "9213859",
      "Mr. Khan Sarwar",
      "0333-",
      "abdulkarim.png"
   ]
]

这个JSON本质上是一个List>。其特殊之处在于：

1. 首行作为键名： 第一个内部列表["S#", "Name of Minister", ...]定义了后续数据行的语义。
2. 后续行作为数据： 从第二个内部列表开始，每一行都代表一个数据记录，其元素值与首行对应的键名一一对应。

由于这种结构并非典型的键值对对象数组，jsonschema2pojo等工具通常无法自动识别并生成带有有意义字段名的POJO。因此，我们需要采用自定义反序列化的方式来解决这个问题。

设计目标POJO模型

为了更好地在Java代码中操作这些数据，我们将为每一行数据设计一个POJO（Plain Old Java Object）。根据JSON的首行标题，我们可以创建一个Minister类，包含相应的字段：

import com.google.gson.annotations.SerializedName;

public class Minister {
    @SerializedName("S#") // 使用SerializedName注解映射JSON中的特殊字符字段
    private String serialNumber;
    @SerializedName("Name of Minister")
    private String name;
    private String portfolio;
    @SerializedName("Contact #")
    private String contactNumber;
    @SerializedName("PRO Name")
    private String proName;
    @SerializedName("PRO Contact")
    private String proContact;
    @SerializedName("PRO Contact #")
    private String proContactNumber;

    // 构造函数
    public Minister(String serialNumber, String name, String portfolio, String contactNumber,
                    String proName, String proContact, String proContactNumber) {
        this.serialNumber = serialNumber;
        this.name = name;
        this.portfolio = portfolio;
        this.contactNumber = contactNumber;
        this.proName = proName;
        this.proContact = proContact;
        this.proContactNumber = proContactNumber;
    }

    // Getter和Setter方法 (此处省略，实际项目中应添加)
    // 例如:
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @Override
    public String toString() {
        return "Minister{" +
               "serialNumber='" + serialNumber + '\'' +
               ", name='" + name + '\'' +
               ", portfolio='" + portfolio + '\'' +
               ", contactNumber='" + contactNumber + '\'' +
               ", proName='" + proName + '\'' +
               ", proContact='" + proContact + '\'' +
               ", proContactNumber='" + proContactNumber + '\'' +
               '}';
    }
}

注意事项：

• 我们使用了@SerializedName注解来映射JSON中包含特殊字符（如#或空格）的字段名到Java的合法变量名。
• 为了简洁，这里省略了所有的getter和setter方法，但在实际项目中应完整添加。

实现自定义JSON反序列化器 (以Gson为例)

由于Retrofit2通常与Gson、Jackson或Moshi等JSON处理库配合使用，我们将以Gson为例，实现一个自定义的反序列化器来解析上述特殊JSON结构。

首先，确保你的项目中已添加Gson和Retrofit的依赖：

// build.gradle (Module: app)
dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'com.google.code.gson:gson:2.10.1'
}

接下来，创建MinisterListDeserializer类，它将负责将整个JSON数组反序列化为List：

LogoMaker

免费在线制作Logo，在几分钟内完成标志设计

下载

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

public class MinisterListDeserializer implements JsonDeserializer> {

    @Override
    public List deserialize(JsonElement json, Type typeOfT, JsonDeserializationContext context) throws JsonParseException {
        List ministers = new ArrayList<>();

        // 确保传入的是一个JSON数组
        if (!json.isJsonArray()) {
            throw new JsonParseException("Expected a JSON array but got: " + json.getClass().getName());
        }

        JsonArray jsonArray = json.getAsJsonArray();

        // 至少需要有标题行和一行数据
        if (jsonArray.size() < 2) {
            // 如果只有标题行或更少，则返回空列表或抛出异常
            return ministers;
        }

        // 提取标题行
        JsonArray headerRow = jsonArray.get(0).getAsJsonArray();
        List headers = new ArrayList<>();
        for (JsonElement headerElement : headerRow) {
            headers.add(headerElement.getAsString());
        }

        // 遍历数据行 (从索引1开始)
        for (int i = 1; i < jsonArray.size(); i++) {
            JsonArray dataRow = jsonArray.get(i).getAsJsonArray();

            // 确保数据行与标题行长度匹配，或者至少不越界
            if (dataRow.size() != headers.size()) {
                // 可以选择跳过不匹配的行，或者抛出异常
                System.err.println("Warning: Data row at index " + i + " has " + dataRow.size() +
                                   " elements, but expected " + headers.size() + " elements based on headers. Skipping this row.");
                continue;
            }

            // 根据标题和数据创建Minister对象
            String serialNumber = null;
            String name = null;
            String portfolio = null;
            String contactNumber = null;
            String proName = null;
            String proContact = null;
            String proContactNumber = null;

            for (int j = 0; j < headers.size(); j++) {
                String header = headers.get(j);
                String value = dataRow.get(j).getAsString();

                switch (header) {
                    case "S#":
                        serialNumber = value;
                        break;
                    case "Name of Minister":
                        name = value;
                        break;
                    case "Portfolio":
                        portfolio = value;
                        break;
                    case "Contact #":
                        contactNumber = value;
                        break;
                    case "PRO Name":
                        proName = value;
                        break;
                    case "PRO Contact":
                        proContact = value;
                        break;
                    case "PRO Contact #":
                        proContactNumber = value;
                        break;
                    // 如果有其他字段，可以在这里添加case
                    default:
                        // 忽略未知字段或记录警告
                        break;
                }
            }
            ministers.add(new Minister(serialNumber, name, portfolio, contactNumber, proName, proContact, proContactNumber));
        }
        return ministers;
    }
}

反序列化逻辑详解：

1. 类型检查： 首先确认传入的JSON元素确实是一个数组。
2. 获取标题行： 取得JSON数组的第一个元素（索引为0），将其解析为headerRow，并提取所有标题字符串。
3. 遍历数据行： 从JSON数组的第二个元素（索引为1）开始遍历，每个元素代表一个数据记录。
4. 数据映射： 对于每个数据行，遍历其元素，并结合之前获取的标题行，通过switch语句将值赋给Minister对象的相应字段。
5. 错误处理： 包含了对JSON结构不符合预期（如数据行长度与标题行不匹配）的简单处理，可以根据实际需求进行调整（例如抛出更具体的异常）。

集成到Retrofit2

现在，我们将这个自定义反序列化器集成到Retrofit2中。

1. 配置GsonBuilder： 创建一个Gson实例，并通过GsonBuilder注册MinisterListDeserializer。

   import com.google.gson.Gson;
   import com.google.gson.GsonBuilder;
   import retrofit2.Retrofit;
   import retrofit2.converter.gson.GsonConverterFactory;
   import java.util.List;
   
   public class RetrofitClient {
       private static final String BASE_URL = "http://your.api.base.url/"; // 替换为你的API基地址
       private static Retrofit retrofit = null;
   
       public static Retrofit getClient() {
           if (retrofit == null) {
               // 注册自定义反序列化器
               Gson gson = new GsonBuilder()
                       .registerTypeAdapter(new com.google.common.reflect.TypeToken>(){}.getType(), new MinisterListDeserializer())
                       .create();
   
               retrofit = new Retrofit.Builder()
                       .baseUrl(BASE_URL)
                       .addConverterFactory(GsonConverterFactory.create(gson)) // 使用配置好的Gson
                       .build();
           }
           return retrofit;
       }
   }

   注意： new com.google.common.reflect.TypeToken>(){}.getType() 用于获取List的泛型类型，这在Java的泛型擦除机制下是必要的。你需要添加Guava库的依赖：implementation 'com.google.guava:guava:32.1.3-android'。如果不想引入Guava，也可以直接使用Type type = new TypeToken>() {}.getType();，但需要确保TypeToken是com.google.gson.reflect.TypeToken。

2. 定义API服务接口： 创建一个Retrofit服务接口，定义获取数据的方法。

   import retrofit2.Call;
   import retrofit2.http.GET;
   import java.util.List;
   
   public interface ApiService {
       @GET("your_endpoint_here") // 替换为你的API端点
       Call> getMinisters();
   }

使用示例

现在，你可以在你的应用程序中调用这个API服务来获取并使用Minister对象的列表了：

import retrofit2.Call;
import retrofit2.Callback;
import retrofit2.Response;
import java.util.List;

public class MainActivity { // 示例，实际可能在Activity或ViewModel中
    public void fetchData() {
        ApiService apiService = RetrofitClient.getClient().create(ApiService.class);
        Call> call = apiService.getMinisters();

        call.enqueue(new Callback>() {
            @Override
            public void onResponse(Call> call, Response> response) {
                if (response.isSuccessful() && response.body() != null) {
                    List ministers = response.body();
                    for (Minister minister : ministers) {
                        System.out.println(minister.toString());
                    }
                    // 在这里处理获取到的Minister列表数据
                } else {
                    System.err.println("API call failed: " + response.code() + " " + response.message());
                }
            }

            @Override
            public void onFailure(Call> call, Throwable t) {
                System.err.println("Network error: " + t.getMessage());
                t.printStackTrace();
            }
        });
    }

    public static void main(String[] args) {
        // 假设在非Android环境运行，RetrofitClient需要配置好MockServer或真实URL
        // 在Android中，通常在Activity或Fragment的生命周期方法中调用fetchData()
        new MainActivity().fetchData();
    }
}

注意事项与最佳实践

1. 错误处理与健壮性：
   • 在MinisterListDeserializer中，对json.isJsonArray()、jsonArray.size()以及dataRow.size()等进行严格的检查，可以有效防止因JSON结构不符合预期而导致的运行时异常。
   • 对于数据缺失或类型不匹配的情况，可以根据业务需求选择抛出异常、返回默认值或记录警告。
2. 性能考量：
   • 对于非常庞大的数据集，自定义反序列化可能涉及较多的字符串操作和对象创建。如果性能成为瓶颈，可以考虑更底层的JSON解析库（如JsonReader）或优化deserialize方法的逻辑。
3. 灵活性与维护：
   • 当前deserialize方法中的switch语句是硬编码的字段名。如果JSON的标题行可能动态变化，可以考虑使用Java反射机制来动态设置POJO字段，但这会增加代码的复杂性和运行时开销。
   • 为了提高可维护性，可以将标题与字段的映射关系抽离成一个配置，而不是硬编码在switch中。
4. 其他JSON库：
   • Jackson： Jackson提供了@JsonCreator和@JsonProperty注解，以及StdDeserializer机制，同样可以实现自定义反序列化。其实现方式与Gson类似，核心思想都是手动解析JSON树并构建Java对象。
   • Moshi： Moshi通过JsonAdapter实现自定义类型适配，提供更简洁的API和编译时代码生成能力，对于复杂类型处理也十分强大。
   • Fastjson： 原始答案中提到了Fastjson。Fastjson同样可以解析为List>，例如JSON.parseObject(jsonString, new TypeReference>>(){})。但若要将这种List>映射到带有命名字段的MinisterPOJO，仍需编写类似的自定义逻辑（如遍历列表并手动构建Minister对象），或者利用其自定义反序列化器功能。本质上，解决思路是共通的：将原始结构解析为中间表示，然后手动映射到目标POJO。

总结

处理非标准JSON结构是API集成中常见的挑战之一。通过本教程介绍的自定义反序列化器方法，我们能够灵活、精确地将任意复杂或非标准的JSON数据映射到我们定义的Java POJO模型中。这不仅确保了