Spring Boot：自定義 Jackson ObjectMapper

1. 概述

在使用JSON格式時，Spring Boot將使用一個ObjectMapper實例來序列化響應和反序列化請求。

在本教程中，我們將探討配置序列化和反序列化選項的最常見方法。

要了解更多關於Jackson的信息，請務必查看我們的Jackson教程。

2. 默認配置

默認情況下，Spring Boot 配置將禁用以下內容：

MapperFeature.DEFAULT_VIEW_INCLUSION
DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES
SerializationFeature.WRITE_DATES_AS_TIMESTAMPS

讓我們先來看一個快速示例：

客户端將向我們的 /coffee?name=Lavazza 發送一個 GET 請求。
控制器將返回一個新的 Coffee 對象。
Spring 將使用 ObjectMapper 將我們的 POJO 序列化為 JSON。

我們將通過使用 String 和 LocalDateTime 對象來演示自定義選項：

public class Coffee {

    private String name;
    private String brand;
    private LocalDateTime date;

   //getters and setters
}

我們還將定義一個簡單的 REST 控制器來演示序列化：

@GetMapping("/coffee")
public Coffee getCoffee(@RequestParam(name = "brand", required = false) String brand,
    @RequestParam(name = "name", required = false) String name) {
    return new Coffee()
      .setBrand(brand)
      .setDate(FIXED_DATE)
      .setName(name);
}

默認情況下，調用 GET http://lolcahost:8080/coffee?brand=Lavazza 時，響應如下：

{
  "name": null,
  "brand": "Lavazza",
  "date": "2020-11-16T10:21:35.974"
}

我們想要排除 null 值並使用自定義日期格式（dd-MM-yyyy HH:mm）。這是我們的最終響應：

{
  "brand": "Lavazza",
  "date": "04-11-2020 10:34"
}

當使用 Spring Boot 時，我們有選項可以自定義默認的 ObjectMapper 或覆蓋它。我們將涵蓋這兩個選項在下一部分。

3. 定製默認的 ObjectMapper

在本節中，我們將看到如何自定義 Spring Boot 使用的默認 ObjectMapper。

3.1. 應用屬性和自定義 Jackson 模塊

配置映射器最簡單的方法是使用應用程序屬性。

配置的通用結構如下:

spring.jackson.<category_name>.<feature_name>=true,false

例如，我們將添加以下內容以禁用 SerializationFeature.WRITE_DATES_AS_TIMESTAMPS:

spring.jackson.serialization.write-dates-as-timestamps=false

除了提到的功能類別之外，我們還可以配置屬性包含:

spring.jackson.default-property-inclusion=always, non_null, non_absent, non_default, non_empty

使用環境變量配置是最簡單的做法。 這種方法的缺點是，我們無法自定義高級選項，例如為 LocalDateTime 設置自定義日期格式。

此時，我們會得到以下結果:

{
  "brand": "Lavazza",
  "date": "2020-11-16T10:35:34.593"
}

為了實現我們的目標，我們將註冊一個新的 JavaTimeModule，並使用自定義日期格式:

@Configuration
@PropertySource("classpath:coffee.properties")
public class CoffeeRegisterModuleConfig {

    @Bean
    public Module javaTimeModule() {
        JavaTimeModule module = new JavaTimeModule();
        module.addSerializer(LOCAL_DATETIME_SERIALIZER);
        return module;
    }
}

此外，配置屬性文件 coffee.properties 將包含以下內容:

spring.jackson.default-property-inclusion=non_null

Spring Boot 將自動註冊任何類型為 com.fasterxml.jackson.databind.Module 的 Bean。我們的最終結果如下:

{
  "brand": "Lavazza",
  "date": "16-11-2020 10:43"
}

3.2. Jackson2ObjectMapperBuilderCustomizer

此函數接口的目的是允許我們創建配置 Bean。

它們將被應用於通過 Jackson2ObjectMapperBuilder 創建的默認 ObjectMapper。

@Bean
public Jackson2ObjectMapperBuilderCustomizer jsonCustomizer() {
    return builder -> builder.serializationInclusion(JsonInclude.Include.NON_NULL)
      .serializers(LOCAL_DATETIME_SERIALIZER);
}

配置 Bean 在特定順序中應用，我們可以使用 @Order 註解來控制此順序。 這種優雅的方法適用於我們希望從不同的配置或模塊配置 ObjectMapper 的情況。

4. 自定義配置

如果我們需要完全控制配置，則有幾種選項可以禁用自動配置，僅允許應用我們自定義的配置。

讓我們仔細研究這些選項。

4.1. ObjectMapper

最簡單的方法是定義一個 ObjectMapper 託管對象，並將其標記為 @Primary：

@Bean
@Primary
public ObjectMapper objectMapper() {
    JavaTimeModule module = new JavaTimeModule();
    module.addSerializer(LOCAL_DATETIME_SERIALIZER);
    return new ObjectMapper()
      .setSerializationInclusion(JsonInclude.Include.NON_NULL)
      .registerModule(module);
}

我們應該使用這種方法來完全控制序列化過程，並且不想允許外部配置。

4.2. Jackson2ObjectMapperBuilder

另一種簡潔的方法是定義一個 Jackson2ObjectMapperBuilder 託管對象。

Spring Boot 默認情況下使用此構建器來構建 ObjectMapper，並且會自動拾取定義的構建器：

@Bean
public Jackson2ObjectMapperBuilder jackson2ObjectMapperBuilder() {
    return new Jackson2ObjectMapperBuilder().serializers(LOCAL_DATETIME_SERIALIZER)
      .serializationInclusion(JsonInclude.Include.NON_NULL);
}

它將默認配置兩個選項：

禁用 MapperFeature.DEFAULT_VIEW_INCLUSION
禁用 DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES

根據 Jackson2ObjectMapperBuilder 文檔，如果類路徑上存在模塊，它還將註冊一些模塊：

jackson-datatype-jdk8：對 Java 8 類型（如 Optional）的支持
jackson-datatype-jsr310：對 Java 8 Date 和 Time API 類型支持
jackson-datatype-joda：對 Joda-Time 類型支持
jackson-module-kotlin：對 Kotlin 類和數據類支持

這種方法的優勢在於 Jackson2ObjectMapperBuilder 提供了一種簡單直觀的方式來構建 ObjectMapper。

4.3. MappingJackson2HttpMessageConverter

只需定義一個類型為 MappingJackson2HttpMessageConverter 的託管對象，Spring Boot 將自動使用它：

@Bean
public MappingJackson2HttpMessageConverter mappingJackson2HttpMessageConverter() {
    Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder().serializers(LOCAL_DATETIME_SERIALIZER)
      .serializationInclusion(JsonInclude.Include.NON_NULL);
    return new MappingJackson2HttpMessageConverter(builder.build());
}

請查看我們的 Spring Http Message Converters 文章以瞭解更多信息。

5. 測試配置

為了測試我們的配置，我們將使用 TestRestTemplate 並將對象序列化為 String。

這樣，我們就可以驗證我們的 Coffee 對象在沒有 null 值並且使用自定義日期格式的情況下被序列化。

@Test
public void whenGetCoffee_thenSerializedWithDateAndNonNull() {
    String formattedDate = DateTimeFormatter.ofPattern(CoffeeConstants.dateTimeFormat).format(FIXED_DATE);
    String brand = "Lavazza";
    String url = "/coffee?brand=" + brand;
    
    String response = restTemplate.getForObject(url, String.class);
    
    assertThat(response).isEqualTo("{\"brand\":\"" + brand + "\",\"date\":\"" + formattedDate + "\"}");
}

6. 結論

在本文中，我們探討了在 Spring Boot 中配置 JSON 序列化選項的幾種方法。

我們看到了兩種不同的方法：配置默認選項或覆蓋默認配置。