场景描述
在软件开发中，数据模型演进是常态。一个常见场景是，某个字段最初设计为存储单个字符串，例如：
public class TestClass {
// String field; // 之前的设计
}随着业务需求变化，该字段需要能够存储多个字符串，因此将其类型修改为List
public class TestClass {
List field; // 当前的设计
} 然而，问题在于数据库中可能已经存储了大量的旧数据，这些数据以JSON格式保存，其中field字段仍然是单个字符串（例如"value"），而不是一个字符串数组（例如["value"]）。当使用Jackson ObjectMapper尝试将这些旧的JSON数据反序列化到新的TestClass时，Jackson会因为类型不匹配而抛出异常，因为它无法直接将一个JSON字符串解析为List
解决方案
为了解决这个问题，我们需要指示Jackson在遇到单个字符串时，将其视为一个包含该字符串的单元素列表进行解析。Jackson提供了两种主要方法来实现这一目标。
方法一：使用 @JsonFormat 注解（推荐）
这是最直接且推荐的方法，因为它将兼容性逻辑直接绑定到字段定义上，清晰明了且作用范围精确。
在TestClass的field字段上添加@JsonFormat注解，并指定JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY特性：
import com.fasterxml.jackson.annotation.JsonFormat;
import java.util.List;
public class TestClass {
@JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
List field;
// 构造函数、Getter/Setter等
public TestClass() {}
public TestClass(List field) {
this.field = field;
}
public List getField() {
return field;
}
public void setField(List field) {
this.field = field;
}
@Override
public String toString() {
return "TestClass{" +
"field=" + field +
'}';
}
} 示例代码：
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;
public class DeserializationDemo {
public static void main(String[] args) throws JsonProcessingException {
ObjectMapper objectMapper = new ObjectMapper();
// 旧数据格式：field是一个字符串
String oldJson = "{\"field\":\"singleValue\"}";
TestClass oldData = objectMapper.readValue(oldJson, TestClass.class);
System.out.println("解析旧数据: " + oldData); // 输出: TestClass{field=[singleValue]}
// 新数据格式：field是一个字符串列表
String newJson = "{\"field\":[\"value1\",\"value2\"]}";
TestClass newData = objectMapper.readValue(newJson, TestClass.class);
System.out.println("解析新数据: " + newData); // 输出: TestClass{field=[value1, value2]}
// 验证空值或null的情况
String nullJson = "{\"field\":null}";
TestClass nullData = objectMapper.readValue(nullJson, TestClass.class);
System.out.println("解析null数据: " + nullData); // 输出: TestClass{field=null}
String emptyListJson = "{\"field\":[]}";
TestClass emptyListData = objectMapper.readValue(emptyListJson, TestClass.class);
System.out.println("解析空列表数据: " + emptyListData); // 输出: TestClass{field=[]}
}
}通过这个注解，Jackson在反序列化时会智能地处理field字段：如果遇到一个字符串，它会自动将其包装成一个单元素列表；如果遇到一个数组，则按常规方式解析。
方法二：通过 ObjectMapper 配置
如果无法修改TestClass的源代码（例如，它是一个第三方库的类），或者希望将此行为应用于所有List类型的字段（全局配置），则可以在ObjectMapper实例上启用此特性。
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;
public class GlobalDeserializationDemo {
public static void main(String[] args) throws JsonProcessingException {
ObjectMapper objectMapper = new ObjectMapper();
// 启用全局特性：允许将单值解析为数组
objectMapper.enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY);
// 假设 TestClass 没有 @JsonFormat 注解
// public class TestClass { List field; ... }
// 旧数据格式：field是一个字符串
String oldJson = "{\"field\":\"singleValue\"}";
TestClass oldData = objectMapper.readValue(oldJson, TestClass.class);
System.out.println("解析旧数据 (全局配置): " + oldData);
// 新数据格式：field是一个字符串列表
String newJson = "{\"field\":[\"value1\",\"value2\"]}";
TestClass newData = objectMapper.readValue(newJson, TestClass.class);
System.out.println("解析新数据 (全局配置): " + newData);
}
} 注意事项：
-
作用范围：
- @JsonFormat注解是字段级别的，只影响被注解的特定字段。这是推荐的方式，因为它提供了更精细的控制，避免了意外的副作用。
- objectMapper.enable(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY)是全局级别的，会影响所有通过该ObjectMapper实例进行反序列化的List类型字段。如果应用程序中有其他List字段不希望有这种行为，全局启用可能会导致问题。
- 优先级： 字段上的注解通常会覆盖ObjectMapper的全局配置。
- 性能： 这两种方法在性能上差异不大，主要考虑的是代码的可维护性和作用范围。
总结
在处理数据模型演进，特别是将字段从单值类型（如String）升级到集合类型（如List
