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);
}

默認情況下，調用 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 Bean，並將其標記為 @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 Bean。

Spring Boot 默認情況下使用這個 Builder 構建 ObjectMapper，並且會自動拾取定義的 Builder。

@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 的 Bean，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 序列化選項的幾種方法。

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

知識庫 / Spring / Spring Boot RSS 訂閱