从零搭建开发脚手架 Jackson使用心得和常用注解

左手的ㄟ右手 2022-09-10 06:26 288阅读 0赞

> 不要用fastjson，至于为什么，自行百度斟酌

Spring Boot使用HttpMessageConverters处理HTTP交换中的内容转换。当classpath中存在Jackson时，Jackson2ObjectMapperBuilder将是默认的Converter.

在一个HTTP交互中，Spring MVC（客户端和服务端）使用`HttpMessageConverters`协商内容转换。如果classpath下存在Jackson，你就获取到`Jackson2ObjectMapperBuilder`提供的默认转换器，这是Spring Boot为你自动配置的实例。

## SpringBoot自定义ObjectMapper ##

默认情况下，Spring Boot 配置将：

*  禁用 - `MapperFeature.DEFAULT_VIEW_INCLUSION`
 *  禁用 - `DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES`
 *  禁用 - `SerializationFeature.WRITE_DATES_AS_TIMESTAMPS`
    
     *  禁用 - 时间序列化为长整型时间戳

### 通过自定义配置文件 ###

yaml中可自定义配置

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

### Jackson2ObjectMapperBuilderCustomizer(推荐) ###

这个接口允许我们创建配置bean。通过`Jackson2ObjectMapperBuilder`创建默认`ObjectMapper`：

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

**配置 bean 以特定的顺序应用，我们可以使用@Order 注释来控制**。如果我们想从不同的配置或模块配置ObjectMapper，这种优雅的方法是合适的。

配置属性如下：https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/\#howto.spring-mvc.customize-jackson-objectmapper

**实际使用**

@Component
    public class JacksonCustomizer implements Jackson2ObjectMapperBuilderCustomizer { 
    
        private static final String STANDARD_PATTERN = "yyyy-MM-dd HH:mm:ss";
    
        private static final String DATE_PATTERN = "yyyy-MM-dd";
    
        private static final String TIME_PATTERN = "HH:mm:ss";
    
        @Override
        public void customize(Jackson2ObjectMapperBuilder builder) { 
            // 初始化JavaTimeModule
            JavaTimeModule javaTimeModule = new JavaTimeModule();
    
            //处理LocalDateTime
            DateTimeFormatter dateTimeFormatter = DateTimeFormatter
                .ofPattern(STANDARD_PATTERN);
            javaTimeModule.addSerializer(LocalDateTime.class, 
                                         new LocalDateTimeSerializer(dateTimeFormatter));
            javaTimeModule.addDeserializer(LocalDateTime.class, 
                                           new LocalDateTimeDeserializer(dateTimeFormatter));
    
            //处理LocalDate
            DateTimeFormatter dateFormatter = DateTimeFormatter.ofPattern(DATE_PATTERN);
            javaTimeModule.addSerializer(LocalDate.class, 
                                         new LocalDateSerializer(dateFormatter));
            javaTimeModule.addDeserializer(LocalDate.class, 
                                           new LocalDateDeserializer(dateFormatter));
    
            //处理LocalTime
            DateTimeFormatter timeFormatter = DateTimeFormatter.ofPattern(TIME_PATTERN);
            javaTimeModule.addSerializer(LocalTime.class, 
                                         new LocalTimeSerializer(timeFormatter));
            javaTimeModule.addDeserializer(LocalTime.class, 
                                           new LocalTimeDeserializer(timeFormatter));
    
            /* * 1. java.util.Date yyyy-MM-dd HH:mm:ss * 2. 支持JDK8 LocalDateTime、LocalDate、 LocalTime * 3. Jdk8Module模块支持如Stream、Optional等类 * 4. 序列化时包含所有字段 * 5. 在序列化一个空对象时时不抛出异常 * 6. 忽略反序列化时在json字符串中存在, 但在java对象中不存在的属性 */
            builder.simpleDateFormat(STANDARD_PATTERN)
                    .modules(javaTimeModule, new Jdk8Module())
                    .serializationInclusion(JsonInclude.Include.ALWAYS)
                    .failOnEmptyBeans(false)
                    .failOnUnknownProperties(false);
        }
    }

### 覆盖默认配置 ###

如果我们想完全控制配置，**有几个选项可以禁用自动配置并只允许应用我们的自定义配置**。

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

**当我们想要完全控制序列化过程并且我们不想允许外部配置时，我们应该使用这种方法**。

#### Jackson2ObjectMapperBuilder ####

另一种干净的方法是定义一个*Jackson2ObjectMapperBuilder* bean *。实际上，Spring Boot 在构建ObjectMapper*时默认使用此构建器，并会自动选择定义的构建器：

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

根据[*Jackson2ObjectMapperBuilder*文档][Jackson2ObjectMapperBuilder]，如果它们存在于类路径中，它还会注册一些模块：

*  jackson-datatype-jdk8：支持其他 Java 8 类型，如*Optional*
 *  jackson-datatype-jsr310：支持 Java 8 日期和时间 API 类型
 *  jackson-datatype-joda：支持 Joda-Time 类型
 *  jackson-module-kotlin：支持 Kotlin 类和数据类

**这种方法的优点是Jackson2ObjectMapperBuilder提供了一种简单直观的方法来构建ObjectMapper**。

### 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 消息转换器][Spring Http]文章以了解更多信息。

### 全局配置 ###

底层默认是通过Jackson2ObjectMapperBuilderCustomizer创建的ObjectMapper

@Configuration
    public class LocalDateTimeSerializerConfig { 
    
        private static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
        private static final DateTimeFormatter DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd");
        private static final DateTimeFormatter TIME_FORMATTER = DateTimeFormatter.ofPattern("HH:mm:ss");
    
    
        @Bean
        public Jackson2ObjectMapperBuilderCustomizer jackson2ObjectMapperBuilderCustomizer() { 
            Map<Class<?>, JsonSerializer<?>> serializers = new HashMap<>();
            serializers.put(LocalDateTime.class, new LocalDateTimeSerializer(DATE_TIME_FORMATTER));
            serializers.put(LocalDate.class, new LocalDateSerializer(DATE_FORMATTER));
            serializers.put(LocalTime.class, new LocalTimeSerializer(TIME_FORMATTER));
    
            Map<Class<?>, JsonDeserializer<?>> deserializers = new HashMap<>();
            deserializers.put(LocalDateTime.class, new LocalDateTimeDeserializer(DATE_TIME_FORMATTER));
            deserializers.put(LocalDate.class, new LocalDateDeserializer(DATE_FORMATTER));
            deserializers.put(LocalTime.class, new LocalTimeDeserializer(TIME_FORMATTER));
            return builder -> builder.serializersByType(serializers).deserializersByType(deserializers);
        }
    }

## 常用注解 ##

### @JsonFormat ###

用于指定如何格式化 JSON 的字段和属性。例如时间类型字段的格式化，jackson提供，当前端传来json串，后台用@ReuqestBody接收，用@JsonFormat 规定接收的时间格式。可用于json格式的序列化和反序列化。

//设置时区为上海时区，时间格式自己据需求定。
        @JsonFormat(pattern="yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
        private Date time;

### @DataTimeFormat ###

用于指定如何格式化 JSON **输入**的字段和属性。例如时间类型字段的格式化，**注意这里只能用于反序列化时，前台输入数据到后台时。spring提供，当前端传来的是键值对**，用@DateTimeFormat 规定接收的时间格式。

Response get(@PathVariable Long id,@DateTimeFormat(pattern = "yyyy-MM-dd") Date time)

后端返回给前端的时间值，只能用@JsonFormat 规定返回格式，@DateTimeFormat 无法决定返回值的格式。

### @JsonPropertyOrder ###

用于指定**序列化属性的顺序**。

@JsonPropertyOrder({  "name", "id" })
    public class MyBean { 
        public int id;
        public String name;
    }
    ---
    { 
        "name":"My bean",
        "id":1
    }

### @JsonRawValue ###

用于指定json格式的string类型

public class RawBean { 
        public String name;
        @JsonRawValue
        public String json;
    }

序列化实体的输出是：

{ 
        "name":"My bean",
        "json":{ 
            "attr":false
        }
    }

### @JsonAlias ###

指定**反序列化**过程属性的一个或多个的别名。

让我们通过一个简单的例子来看看这个注解是如何工作的：

public class AliasBean { 
        @JsonAlias({  "fName", "f_name" })
        private String firstName;   
        private String lastName;
    }
    ---
    { 
    	"fName": "laker",
        "lastName": "laker2"
    }

### @JsonIgnoreProperties ###

类级别的注解，用于标记 Jackson 将忽略的属性或属性列表。

@JsonIgnoreProperties({  "id" })
    public class BeanWithIgnore { 
        public int id;
        public String name;
    }

序列化的结果是不包含id属性的

### @JsonIgnore ###

用于在字段级别标记要忽略的属性。

public class BeanWithIgnore { 
        @JsonIgnore
        public int id;
        public String name;
    }

序列化的结果是不包含id属性的

### @JsonProperty ###

public class MyBean { 
        public int id;
        private String name;
        @JsonProperty("name")
        public void setTheName(String name) { 
            this.name = name;
        }
        @JsonProperty("name")
        public String getTheName() { 
            return name;
        }
    }

## 常见功能 ##

### 格式化PrettyJson ###

ObjectMapper mapper = new ObjectMapper();
    String jsonResult = mapper.writerWithDefaultPrettyPrinter()
      .writeValueAsString(map);

### 枚举类型描述 ###

/** * 事故类型 */
        private AccidentTypeEnum accidentType;
    
        /** * 事故类型描述 */
        @JsonGetter
        private String getAccidentTypeDes() { 
            if (accidentType == null) { 
                return "";
            }
            return accidentType.getDescp();
        }

### 指定某个字段序列化和反序列化 ###

/**
     * 因为密码比较重要，故仅用于反序列化
     */
    @JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
    private String password;

### 时间序列化和反序列化 ###

//设置时区为上海时区，时间格式自己据需求定。
    @JsonFormat(pattern="yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
    private Date time;

### 反序列化List ###

public static <T> List<T> jsonArrayToList(String json, Class<T> elementClass) throws IOException { 
        ObjectMapper objectMapper = new ObjectMapper();
        CollectionType listType = objectMapper.getTypeFactory().constructCollectionType(ArrayList.class, elementClass);
        return objectMapper.readValue(json, listType);
    }

### 反序列化Map ###

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

### 使用JsonNode进行各种转换以及添加、修改和删除节点 ###

#### 创建节点 ####

从无到有创建节点的最常见方法如下：

JsonNode node = mapper.createObjectNode();

或者，我们也可以通过JsonNodeFactory创建一个节点：

JsonNode node = JsonNodeFactory.instance.objectNode();

从字符串创建节点

String jsonString = "{"k1":"v1","k2":"v2"}";
       ObjectMapper mapper = new ObjectMapper();
       JsonNode actualObj = mapper.readTree(jsonString);

从对象创建节点

可以通过调用*ObjectMapper*上的\*valueToTree(Object fromValue)\*方法从 Java 对象转换节点：

JsonNode node = mapper.valueToTree(fromValue);

或者

JsonNode node = mapper.convertValue(fromValue, JsonNode.class);

#### 转换节点 ####

NodeBean toValue = mapper.treeToValue(node, NodeBean.class);

这在功能上等同于：

NodeBean toValue = mapper.convertValue(node, NodeBean.class)

#### 定位节点 ####

在处理任何节点之前，我们需要做的第一件事是定位它并将其分配给一个变量。

如果事先知道节点的路径，这很容易做到。例如，假设我们想要一个名为`last`的节点，它位于`node`下：

JsonNode locatedNode = rootNode.path("name").path("last");

或者，也可以使用**get**或**with**API 代替*path*。

如果路径未知，搜索当然会变得更加复杂和迭代。

#### 添加新节点 ####

一个节点可以添加为另一个节点的子节点，如下所示：

ObjectNode newNode = ((ObjectNode) locatedNode).put(fieldName, value);

*put 的*许多重载变体可用于添加不同值类型的新节点。

许多其他类似的方法也可用，包括*putArray*、*putObject*、*PutPOJO*、*putRawValue*和*putNull*。

#### 编辑节点 ####

一个*ObjectNode*实例可以通过调用被修改字符串fieldName，JsonNode值方法：

JsonNode locatedNode = locatedNode.set(fieldName, value);

通过在相同类型的对象上使用replace或setAll方法可以实现类似的结果。

#### 删除节点 ####

可以通过在其父节点上调用*remove(String fieldName)* API来删除节点：

JsonNode removedNode = locatedNode.remove(fieldName);

为了一次删除多个节点，我们可以调用一个带有Collection类型参数的重载方法，它返回父节点而不是要删除的节点：

ObjectNode locatedNode = locatedNode.remove(fieldNames);

在极端情况下，当我们想删除一个给定节点的所有子节点\*-*的*的removeAll\* API就派上用场了。

#### 迭代节点 ####

JSON 有三种类型的节点，分别是值、对象和数组。

因此，让我们通过添加一个*数组来*确保我们的示例数据具有所有三种不同的类型

#### 处理不同的节点类型 ####

我们需要稍微不同地处理不同类型的节点。我们将在*processNode*方法中执行此操作：

if (jsonNode.isValueNode()) { 
        yaml.append(jsonNode.asText());
    }
    if (jsonNode.isArray()) { 
        for (JsonNode arrayItem : jsonNode) { 
    	}
    }
    if (jsonNode.isObject()) { 
    }

[Jackson2ObjectMapperBuilder]: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/converter/json/Jackson2ObjectMapperBuilder.html
[Spring Http]: https://www.baeldung.com/spring-httpmessageconverter-rest