Jackson ObjectMapper 入门

1. 概述

本教程重点介绍 Jackson ObjectMapper 类，以及如何将 Java 对象序列化为 JSON，以及将 JSON 字符串反序列化为 Java 对象。

要更深入地了解 Jackson 库，Jackson 教程是一个不错的起点。

2. 依赖项

首先，我们将以下依赖项添加到 pom.xml

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

此依赖项还将传递性地将以下库添加到类路径

1. jackson-annotations
2. jackson-core

始终从 Maven 中央仓库使用最新版本jackson-databind。

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

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

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 方法生成 JSON 并将生成的 JSON 作为字符串或字节数组返回

String carAsString = objectMapper.writeValueAsString(car);

3.2. JSON 到 Java 对象

以下是使用 ObjectMapper 类将 JSON 字符串转换为 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\" }";

上述示例中的 JSON 字符串在默认解析过程到 Car 类的 Java 对象时，将导致 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类的另一个重要特性是能够注册自定义序列化器和反序列化器。

在输入或输出 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的默认序列化会生成一个数字，即 epoch 时间戳（自 1970 年 1 月 1 日 UTC 以来的毫秒数）。但这可读性不高，需要进一步转换才能以人类可读的格式显示。

让我们将到目前为止使用的Car实例包装到具有datePurchased属性的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"}

要了解有关使用 Jackson 序列化日期的更多信息，请阅读我们更深入的介绍。

请注意，在某些情况下，我们在创建 SimpleDateFormat 时还需要指定Locale，以便它在所有机器上产生一致的输出，而与机器运行的区域无关。

要指定Locale，我们可以这样做

SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm a z", Locale.ENGLISH);

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

有关使用 Jackson 处理集合的更多信息，请访问此处。

5. Builder 模式用于ObjectMapper

到目前为止，我们已经学习了配置ObjectMapper实例的不同方法。在本节中，我们将原型化ObjectMapperBuilder类以创建ObjectMapper类的不可变实例。

5.1. ObjectMapperBuilder 类

让我们从创建带有几个配置参数的ObjectMapperBuilder类开始，即enableIdentation、preserveOrder和dateFormat

public class ObjectMapperBuilder {
    private boolean enableIndentation;
    private boolean preserveOrder;
    private DateFormat dateFormat;
}

我们必须注意，ObjectMapper实例有几种可能的配置。我们只关注构建器原型化用例中的一部分可能的配置。

接下来，让我们添加允许我们在创建ObjectMapper类实例时将相应的配置属性设置为构建器的相应方法

ObjectMapperBuilder enableIndentation() {
    this.enableIndentation = true;
    return this;
}

ObjectMapperBuilder dateFormat() {
    SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm a z");
    simpleDateFormat.setTimeZone(TimeZone.getTimeZone(ZoneId.of("Asia/Kolkata")));
    this.dateFormat = simpleDateFormat;
    return this;
}

ObjectMapperBuilder preserveOrder(boolean order) {
    this.preserveOrder = order;
    return this;
}

最后，让我们添加build()方法以返回具有已配置参数的最终ObjectMapper实例

public ObjectMapper build() {
    ObjectMapper objectMapper = new ObjectMapper();

    objectMapper.configure(SerializationFeature.INDENT_OUTPUT, this.enableIndentation);
    objectMapper.setDateFormat(this.dateFormat);
    if (this.preserveOrder) {
        objectMapper.enable(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS);
    }

    return objectMapper;
}

很好！我们已成功原型化了ObjectMapper实例的构建器类。

5.2. Builder 实际操作

让我们使用ObjectMapperBuilder类创建一个ObjectMapper类的单个实例

ObjectMapper mapper = new ObjectMapperBuilder()
  .enableIndentation()
  .dateFormat()
  .preserveOrder(true)
  .build();

现在，让我们定义一个Car类实例及其序列化的 JSON 字符串

Car givenCar = new Car("White", "Sedan");
String givenCarJsonStr = "{ \"color\" : \"White\", \"type\" : \"Sedan\" }";

接下来，让我们使用 mapper 对象反序列化 givenCarJsonStr

Car actual = mapper.readValue(givenCarJsonStr, Car.class);
Assertions.assertEquals("White", actual.getColor());
Assertions.assertEquals("Sedan", actual.getType());

太棒了！看来我们做对了。

最后，让我们验证 Request 类实例的序列化流程

Request request = new Request();
request.setCar(givenCar);
Date date = new Date(1684909857000L);
request.setDatePurchased(date);

String actual = mapper.writeValueAsString(request);
String expected = "{\n" + "  \"car\" : {\n" + "    \"color\" : \"White\",\n" +
    "    \"type\" : \"Sedan\"\n" + "  },\n" + "  \"datePurchased\" : \"2023-05-24 12:00 PM IST\"\n" +
    "}";
Assertions.assertEquals(expected, actual);

很好！我们已经通过 ObjectMapperBuilder 类成功验证了反序列化和序列化操作。

6. 结论

Jackson 是一个成熟稳定的 Java JSON 序列化/反序列化库。ObjectMapper API 提供了一种直接的方法来解析和生成 JSON 响应对象，具有很大的灵活性。此外，我们还原型化了 ObjectMapperBuilder 类，以创建 ObjectMapper 类的不可变实例。本文讨论了使该库如此流行的主要特性。