Java中高效解析JSON/ndJSON文件：Gson与DTO模型匹配实践

本文旨在解决java中使用gson库解析json文件时常见的`jsonsyntaxexception: expected begin_array but was begin_object`错误。核心在于强调json数据结构（对象或数组）与java dto（数据传输对象）中对应字段类型必须严格匹配。教程将通过案例分析、正确模型设计、代码示例及ndjson文件处理方法，指导开发者实现高效、无错的json反序列化。

引言：理解JSON与Java对象映射的挑战

JSON（JavaScript Object Notation）作为一种轻量级的数据交换格式，在现代Web服务和数据处理中扮演着核心角色。在Java应用中，我们经常需要将JSON数据反序列化为Java对象，以便于程序内部处理。Gson是Google提供的一个强大的Java库，用于Java对象和JSON数据之间的序列化和反序列化。然而，在将复杂的JSON结构映射到Java对象时，如果不遵循严格的类型匹配规则，很容易遇到JsonSyntaxException等运行时错误。

案例分析：Expected BEGIN_ARRAY but was BEGIN_OBJECT异常解析

当使用Gson解析JSON时，com.google.gson.JsonSyntaxException: java.lang.IllegalStateException: Expected BEGIN_ARRAY but was BEGIN_OBJECT是一个常见的错误。这个异常清晰地指出了问题所在：Gson在解析JSON时，期望遇到一个数组的开始（[），但实际上却遇到了一个对象的开始（{）。这通常意味着您的Java DTO模型与实际的JSON结构不匹配。

让我们来看一个具体的例子。假设有以下JSON数据片段：

{
   "Top-level":{
      "customer_no":"1",
      "created":"2019-03-27 14:24:54"
   },
   "profile":{
      "salutation":"Mr",
      "first_name":"Veronica"
   },
   "phone":{
      "home_phone":null
   },
   "addresses":[
      {
         "address_id":"1",
         "city":"Calder"
      }
   ],
   "orders":{
      "placed_orders_count":2,
      "0":{
         "order_id":"000000001"
      }
   },
   "customs":[

   ]
}

以及一个尝试解析上述JSON的Java DTO：

立即学习“Java免费学习笔记（深入）”；

public class CustomerFeedDTO {
    private ArrayList topLevel;
    private ArrayList profile;
    private ArrayList phone;
    private ArrayList addresses;
    private ArrayList orders;
    private ArrayList customs;
    // Getters and setters
}

当尝试使用Gson.fromJson(reader, CustomerFeedDTO.class)进行反序列化时，便会抛出Expected BEGIN_ARRAY but was BEGIN_OBJECT at line 1 column 138 path $.profile异常。

原因分析： 仔细比对JSON结构与CustomerFeedDTO会发现：

• JSON中的"Top-level"是一个JSON对象（以{开头）。
• JSON中的"profile"是一个JSON对象（以{开头）。
• JSON中的"phone"是一个JSON对象（以{开头）。
• JSON中的"orders"是一个JSON对象（以{开头）。
• 然而，在CustomerFeedDTO中，topLevel, profile, phone, orders字段都被声明为ArrayList>。

Gson在解析到"profile"字段时，发现JSON中是一个对象，但DTO中却定义为一个列表，因此抛出了类型不匹配的异常。

正确的数据模型（DTO）设计

解决上述问题的关键在于确保Java DTO的字段类型与JSON数据的结构严格匹配。

核心原则：JSON结构与Java类型匹配

• JSON对象 { ... }：应映射到Java的自定义类（POJO - Plain Old Java Object）或 Map 类型。使用自定义类通常是更好的选择，因为它提供了更强的类型安全性和代码可读性。
• JSON数组 [ ... ]：应映射到Java的 List 或 T[] 类型。其中 T 是数组元素的Java类型。
• JSON基本类型（字符串、数字、布尔值、null）：应映射到Java的 String、int/Integer、double/Double、boolean/Boolean 等基本类型或其包装类。

修正后的CustomerFeedDTO

根据上述原则，我们可以修正CustomerFeedDTO如下：

import java.util.ArrayList;
import java.util.Map; // 需要导入Map

public class CustomerFeedDTO {

    // "Top-level" 在JSON中是对象，应映射为Map或自定义类
    private Map topLevel; 
    // "profile" 在JSON中是对象，应映射为Map或自定义类
    private Map profile;
    // "phone" 在JSON中是对象，应映射为Map或自定义类
    private Map phone;
    // "addresses" 在JSON中是数组，映射为ArrayList是正确的
    private ArrayList addresses;
    // "orders" 在JSON中是对象，应映射为Map或自定义类
    private Map orders;
    // "customs" 在JSON中是数组，映射为ArrayList是正确的
    private ArrayList customs;

    // Getters and setters (省略，但实际开发中应包含)
    public Map getTopLevel() { return topLevel; }
    public void setTopLevel(Map topLevel) { this.topLevel = topLevel; }
    public Map getProfile() { return profile; }
    public void setProfile(Map profile) { this.profile = profile; }
    public Map getPhone() { return phone; }
    public void setPhone(Map phone) { this.phone = phone; }
    public ArrayList getAddresses() { return addresses; }
    public void setAddresses(ArrayList addresses) { this.addresses = addresses; }
    public Map getOrders() { return orders; }
    public void setOrders(Map orders) { this.orders = orders; }
    public ArrayList getCustoms() { return customs; }
    public void setCustoms(ArrayList customs) { this.customs = customs; }
}

通过将topLevel, profile, phone, orders字段的类型从ArrayList>更改为Map，我们使得DTO的结构与JSON数据完全匹配，从而解决了JsonSyntaxException。

更佳实践：使用具体POJO类

虽然使用Map可以解决类型匹配问题，但在实际项目中，为每个JSON对象创建具体的Java POJO类是更推荐的做法。这提供了更好的类型安全、代码可读性、IDE自动补全支持以及更强的可维护性。

例如，可以为Top-level、Profile、Phone、Order等创建独立的POJO类：

// TopLevel.java
public class TopLevel {
    private String customer_no;
    private String created;
    private String last_visited_day_time; // 对应JSON中的null
    private String login; // 对应JSON中的email
    // Getters and setters
}

// Profile.java
public class Profile {
    private String salutation;
    private String title;
    private String company;
    private String job_title;
    private String first_name;
    private String last_name;
    private String name_suffix;
    private String gender;
    private String birthday;
    private String email;
    private String next_birthday;
    private String second_name;
    // Getters and setters
}

// Phone.java
public class Phone {
    private String home_phone;
    private String business_phone;
    private String mobile_phone;
    private String fax_number;
    // Getters and setters
}

// Address.java (用于addresses数组中的元素)
public class Address {
    private String address_id;
    private String title;
    // ... 其他地址字段
    private String contact_phone;
    // Getters and setters
}

// OrdersContainer.java (因为orders内部有动态键名"0", "1"等，可以灵活处理)
public class OrdersContainer {
    private int placed_orders_count;
    // 如果键名是数字，Gson默认会尝试映射到Map，或者可以自定义反序列化器
    // 简便起见，这里仍使用Map，或者如果结构固定，可以定义OrderEntry类
    private Map ordersMap; // 假设0, 1是订单ID
    // Getters and setters
    // 注意：Gson会尝试将"0"、"1"作为Map的键。
    // 如果要更优雅地处理，可能需要自定义反序列化器，或者将这些订单视为List
    // 但这需要JSON结构是 [{}, {}] 而不是 {"0":{}, "1":{}}
    // 对于 {"0":{}, "1":{}} 这种结构，Map 是最直接的映射
}

// OrderEntry.java
public class OrderEntry {
    private String order_id;
    private String order_date;
    // Getters and setters
}

// 最终的 CustomerFeedDTO 结构将是：
public class CustomerFeedDTO {
    private TopLevel topLevel;
    private Profile profile;
    private Phone phone;
    private List
 addresses; // 使用 List
 更具体
    private OrdersContainer orders; // 使用 OrdersContainer
    private List