Jackson ObjectMapper详解

1. 概述

本文重点是理解Jackson ObjectMapper类，以及如何将Java对象序列化为JSON和将JSON字符串反序列化为Java对象。

2. 依赖

让我们首先向 pom.xml 中添加以下依赖项:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.13.3</version>
</dependency>

这个依赖还会把以下库传递到 classpath 中:

1. jackson-annotations
2. jackson-core

始终为 [jackson-databind](https://search.maven.org/classic/#search|gav|1|g%3A"com.fasterxml.jackson.core" AND a%3A"jackson-databind") 使用来自 Maven 中央存储库的最新版本。

3. 使用ObjectMapper读写

让我们从基本的读写操作开始。

简单的 ObjectMapper 的 readValue API是一个很好的切入点。我们可以使用它将JSON内容解析或反序列化为Java对象。

另外，在写入方面，我们可以使用writeValue API将任何Java对象序列化为JSON输出。

在本文中，我们将使用下面带有两个字段的Car类作为对象来序列化或反序列化:

public class Car {

    private String color;
    private String type;

    // standard getters setters
}

3.1. Java对象到JSON

让我们来看第一个使用 ObjectMapper 类的 writeValue 方法将Java对象序列化为JSON的例子:

ObjectMapper objectMapper = new ObjectMapper();
Car car = new Car("yellow", "renault");
objectMapper.writeValue(new File("target/car.json"), car);

上述文件中的输出将是:

{"color":"yellow","type":"renault"}

ObjectMapper 类的writeValueAsString 和 writeValueAsBytes 方法从Java对象生成JSON，并以字符串或字节数组的形式返回生成的JSON:

String carAsString = objectMapper.writeValueAsString(car);

3.2. JSON到Java对象

下面是一个使用 ObjectMapper 类将JSON String转换为Java对象的简单示例:

String json = "{ \"color\" : \"Black\", \"type\" : \"BMW\" }";
Car car = objectMapper.readValue(json, Car.class);	

readValue() 函数也接受其他形式的输入，比如包含JSON字符串的文件:

Car car = objectMapper.readValue(new File("src/test/resources/json_car.json"), Car.class);

或一个URL:

Car car = 
  objectMapper.readValue(new URL("file:src/test/resources/json_car.json"), Car.class);

3.3. JSON到Jackson JsonNode

或者，JSON可以被解析为 JsonNode 对象，并用于从特定节点检索数据:

String json = "{ \"color\" : \"Black\", \"type\" : \"FIAT\" }";
JsonNode jsonNode = objectMapper.readTree(json);
String color = jsonNode.get("color").asText();
// Output: color -> Black

3.4. 从JSON数组字符串创建Java List

我们可以使用 TypeReference 将数组形式的JSON解析为Java对象列表:

String jsonCarArray = 
  "[{ \"color\" : \"Black\", \"type\" : \"BMW\" }, { \"color\" : \"Red\", \"type\" : \"FIAT\" }]";
List<Car> listCar = objectMapper.readValue(jsonCarArray, new TypeReference<List<Car>>(){});

3.5. 从JSON字符串创建Java Map

类似地，我们可以将JSON解析为Java Map:

String json = "{ \"color\" : \"Black\", \"type\" : \"BMW\" }";
Map<String, Object> map 
  = objectMapper.readValue(json, new TypeReference<Map<String,Object>>(){});

4. 高级特性

Jackson库最大的优点之一是高度可定制的序列化和反序列化处理器。

在本节中，我们将介绍一些高级功能，其中输入或输出 JSON 响应可能与生成或使用响应的对象不同。

4.1. 配置序列化/反序列化特性

在将JSON对象转换为Java类时，如果JSON字符串有一些新字段，默认过程将导致异常:

String jsonString 
  = "{ \"color\" : \"Black\", \"type\" : \"Fiat\", \"year\" : \"1970\" }";

在对Java对象的Class Car的默认解析过程中，上述示例中的JSON字符串将导致UnrecognizedPropertyException异常。

通过configure方法，我们可以扩展默认处理器以忽略新字段:

objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
Car car = objectMapper.readValue(jsonString, Car.class);

JsonNode jsonNodeRoot = objectMapper.readTree(jsonString);
JsonNode jsonNodeYear = jsonNodeRoot.get("year");
String year = jsonNodeYear.asText();

另一个选项基于 FAIL_ON_NULL_FOR_PRIMITIVES，它定义了是否 null 值原始值是允许的:

objectMapper.configure(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES, false);

类似地，FAIL_ON_NUMBERS_FOR_ENUM控制是否允许将枚举值序列化/反序列化为数字:

objectMapper.configure(DeserializationFeature.FAIL_ON_NUMBERS_FOR_ENUMS, false);

您可以在官方网站上找到序列化和反序列化特性的全面列表。

4.2. 创建自定义序列化器或反序列化器

ObjectMapper类的另一个基本特性是能够注册自定义的 serializer 和 deserializer。

在输入或输出JSON响应的结构与必须序列化或反序列化的Java类的结构不同的情况下，自定义序列化器和反序列化器非常有用。

下面是一个自定义JSON序列化器的例子:

public class CustomCarSerializer extends StdSerializer<Car> {
    
    public CustomCarSerializer() {
        this(null);
    }

    public CustomCarSerializer(Class<Car> t) {
        super(t);
    }

    @Override
    public void serialize(
      Car car, JsonGenerator jsonGenerator, SerializerProvider serializer) {
        jsonGenerator.writeStartObject();
        jsonGenerator.writeStringField("car_brand", car.getType());
        jsonGenerator.writeEndObject();
    }
}

这个自定义序列化器可以像这样调用:

ObjectMapper mapper = new ObjectMapper();

SimpleModule module = 
  new SimpleModule("CustomCarSerializer", new Version(1, 0, 0, null, null, null));
module.addSerializer(Car.class, new CustomCarSerializer());

mapper.registerModule(module);

Car car = new Car("yellow", "renault");
String carJson = mapper.writeValueAsString(car);

下面是Car在客户端的样子(作为JSON输出):

var carJson = {"car_brand":"renault"}

下面是一个自定义JSON反序列化器的例子:

public class CustomCarDeserializer extends StdDeserializer<Car> {
    
    public CustomCarDeserializer() {
        this(null);
    }

    public CustomCarDeserializer(Class<?> vc) {
        super(vc);
    }

    @Override
    public Car deserialize(JsonParser parser, DeserializationContext deserializer) {
        Car car = new Car();
        ObjectCodec codec = parser.getCodec();
        JsonNode node = codec.readTree(parser);
        
        // try catch block
        JsonNode colorNode = node.get("color");
        String color = colorNode.asText();
        car.setColor(color);
        return car;
    }
}

这个自定义反序列化器可以通过以下方式调用:

String json = "{ \"color\" : \"Black\", \"type\" : \"BMW\" }";
ObjectMapper mapper = new ObjectMapper();

SimpleModule module =
  new SimpleModule("CustomCarDeserializer", new Version(1, 0, 0, null, null, null));
module.addDeserializer(Car.class, new CustomCarDeserializer());

mapper.registerModule(module);

Car car = mapper.readValue(json, Car.class);

4.3. 处理日期格式

java.util.Date 的默认序列化生成一个数字，即纪元时间戳（自 1970 年 1 月 1 日以来的毫秒数，UTC）。但这不是人类可读的，需要进一步转换才能以人类可读的格式显示。

让我们用 datePurchased 属性将目前使用的 Car 实例包装在 Request 类中：

public class Request 
{
    private Car car;
    private Date datePurchased;

    // standard getters setters
}

要控制日期的字符串格式并将其设置为例如 yyyy-MM-dd HH:mm a z，请考虑以下代码段：

ObjectMapper objectMapper = new ObjectMapper();
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm a z");
objectMapper.setDateFormat(df);
String carAsString = objectMapper.writeValueAsString(request);
// output: {"car":{"color":"yellow","type":"renault"},"datePurchased":"2016-07-03 11:43 AM CEST"}

4.4. 处理集合

DeserializationFeature 类提供的另一个小但有用的功能是能够从 JSON 数组响应生成我们想要的集合类型。

例如，我们可以将结果生成为数组：

String jsonCarArray = 
  "[{ \"color\" : \"Black\", \"type\" : \"BMW\" }, { \"color\" : \"Red\", \"type\" : \"FIAT\" }]";

ObjectMapper objectMapper = new ObjectMapper();
objectMapper.configure(DeserializationFeature.USE_JAVA_ARRAY_FOR_JSON_ARRAY, true);

Car[] cars = objectMapper.readValue(jsonCarArray, Car[].class);
// print cars

或作为List：

String jsonCarArray = 
  "[{ \"color\" : \"Black\", \"type\" : \"BMW\" }, { \"color\" : \"Red\", \"type\" : \"FIAT\" }]";

ObjectMapper objectMapper = new ObjectMapper();

List<Car> listCar = objectMapper.readValue(jsonCarArray, new TypeReference<List<Car>>(){});
// print cars

5. 结尾

Jackson是一个可靠而成熟的Java JSON序列化/反序列化库。ObjectMapper API提供了一种解析和生成JSON响应对象的简单方法，具有很大的灵活性。本文讨论了使该库如此受欢迎的主要特性。

---

<<<<<<<<<<<< [完] >>>>>>>>>>>>