使用Jackson API将JSONArray转为Java对象时遇反序列化异常

这问题我之前在对接第三方服务时也踩过坑！咱们先把问题拆解清楚：

核心原因 #

你的POJO类OrderHeader中，order_items字段被定义为List<OrderItem>类型，但服务返回的JSON里，这个字段对应的是单个JSON对象（而不是JSON数组）。Jackson在反序列化时，看到的是START_OBJECT（也就是{开头的对象），却要把它转换成ArrayList，自然就抛出了这个类型不匹配的异常。

举个例子，出错的JSON大概率是这样的：

{
  "order_id": "123",
  "order_date": "2024-05-20",
  "order_items": {
    "item_id": "456",
    "item_name": "Test Product"
  }
}

而你的POJO期望的是数组格式的order_items：

"order_items": [
  {
    "item_id": "456",
    "item_name": "Test Product"
  }
]

解决方案 #

根据你的场景，有两种常用的修复方式：

方案1：全局配置Jackson支持单值转数组

如果你希望所有类似的集合字段都能自动处理“单个对象”的情况，可以在你的JsonUtil工具类中配置ObjectMapper，启用ACCEPT_SINGLE_VALUE_AS_ARRAY特性：

public class JsonUtil {
    private static final ObjectMapper objectMapper;

    static {
        objectMapper = new ObjectMapper();
        // 关键配置：允许将单个对象反序列化为集合
        objectMapper.enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY);
        // 可选：忽略JSON中POJO没有的字段，避免额外异常
        objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
    }

    // 数组转对象列表的方法
    public static <T> List<T> convertJsonArrayToObjectList(String json, Class<T> clazz) throws IOException {
        return objectMapper.readValue(json, objectMapper.getTypeFactory().constructCollectionType(List.class, clazz));
    }

    // 单个JSON转对象的方法
    public static <T> T convertJsonToObject(String json, Class<T> clazz) throws IOException {
        return objectMapper.readValue(json, clazz);
    }
}

这个配置会让Jackson自动把单个对象包装成一个包含该对象的集合，完美适配你的List<OrderItem>字段。

方案2：针对单个字段单独配置

如果你只想让order_items字段支持这种转换，不想影响其他字段，可以在POJO的对应字段上添加@JsonFormat注解：

public class OrderHeader {
    // 其他字段示例
    private String order_id;
    private String order_date;

    // 关键注解：仅对这个字段启用单值转数组
    @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
    private List<OrderItem> order_items;

    // Getter和Setter方法...
}

这种方式更精准，不会干扰其他字段的反序列化逻辑。

额外建议

如果服务端本应该返回数组格式的order_items，那最好优先和服务端沟通修复JSON结构——这才是最根本的解决方案。但如果服务端无法修改，上面两种客户端处理方式就能完美解决问题。

内容的提问来源于stack exchange，提问作者Karthikeyan