20221116 Feature

概览

Feature 分类

整体来看，Feature 应该分为 6 套：

1. JsonFactory.Feature

   1. 实现 JacksonFeature

2. JsonParser.Feature 、JsonGenerator.Feature

   1. 将在 Jackson 3 被移除

3. StreamReadFeature 、StreamWriteFeature

   1. 实现 JacksonFeature

   2. 替代 JsonParser.Feature 、JsonGenerator.Feature

   3. 无关数据格式

4. JsonReadFeature 、JsonWriteFeature

5. MapperFeature

   1. 实现 ConfigFeature

6. SerializationFeature 、DeserializationFeature

   1. 实现 ConfigFeature

从层次上看，1-4 更底层，配合读写 JSON ，5-6 配合数据绑定

Feature 搭配 Builder 使用

Builder 继承关系

TSF ：token stream factory

TSFBuilder

• JsonFactoryBuilder

MapperBuilder

• JsonMapper.Builder

搭配关系

• JsonFactoryBuilder

  • JsonFactory.Feature

  • StreamReadFeature

  • StreamWriteFeature

  • JsonReadFeature

  • JsonWriteFeature

• JsonMapper.Builder

  • JsonParser.Feature

  • JsonGenerator.Feature

  • StreamReadFeature

  • StreamWriteFeature

  • JsonReadFeature

  • JsonWriteFeature

  • MapperFeature

  • SerializationFeature

  • DeserializationFeature

JsonFactory.Feature

Symbol handling (interning etc)

Feature	默认状态	描述
INTERN_FIELD_NAMES	true	是否使用 String.intern 规范化 JSON 对象字段名称 只有当 CANONICALIZE_FIELD_NAMES 为 true 时生效
CANONICALIZE_FIELD_NAMES	true	JSON 对象字段名称是否要规范化
FAIL_ON_SYMBOL_HASH_OVERFLOW	true	确定如果我们在符号处理中遇到散列冲突数量超过安全阈值的情况下是否抛出异常
USE_THREAD_LOCAL_FOR_BUFFER_RECYCLING	true	确定是否将 BufferRecycler 与 ThreadLocal 和 SoftReference 一起使用，以有效地重用底层输入输出缓冲区

JsonGenerator.Feature

Low-level I/O / content features

Feature	默认状态	描述
AUTO_CLOSE_TARGET	true	是否自动关闭底层输出流
AUTO_CLOSE_JSON_CONTENT	true	是否自动补全 json（当有不匹配的JsonToken#START_ARRAY、 JsonToken#START_OBJECT时）
FLUSH_PASSED_TO_STREAM	true	调用 flush 方法时，是否调用底层输出流的 flush 方法

Datatype coercion features

Feature	默认状态	描述
WRITE_BIGDECIMAL_AS_PLAIN	false	使用 BigDecimal.toPlainString 输出

Schema/Validity support features

Feature	默认状态	描述
STRICT_DUPLICATE_DETECTION	false	是否启用严格的字段名重复检查
IGNORE_UNKNOWN	false	属性定义未找到是否报错

JsonParser.Feature

Low-level I/O handling features

Feature	默认状态	描述
AUTO_CLOSE_SOURCE	true	是否自动关闭底层输入流

Support for non-standard data format constructs

Feature	默认状态	描述
ALLOW_COMMENTS	false	是否允许注释
ALLOW_YAML_COMMENTS	false	是否允许出现 yaml 注释
ALLOW_UNQUOTED_FIELD_NAMES	false	是否允许出现字段名不带引号
ALLOW_SINGLE_QUOTES	false	是否允许出现单引号

Validity checks

Feature	默认状态	描述
STRICT_DUPLICATE_DETECTION	false	是否启用严格的字段名重复检查
IGNORE_UNDEFINED	false	属性定义未找到是否报错

Other

Feature	默认状态	描述
INCLUDE_SOURCE_IN_LOCATION	true	是否包含其源信息（如总字节数，总字符数 行号 列号 ）

StreamWriteFeature

Token writer (generator) 功能不特定于任何特定格式。最终替代非 JSON 特定的 JsonGenerator.Features

Low-level I/O / content features

Feature	对应 JsonGenerator.Feature
AUTO_CLOSE_TARGET	AUTO_CLOSE_TARGET
AUTO_CLOSE_CONTENT	AUTO_CLOSE_JSON_CONTENT
FLUSH_PASSED_TO_STREAM	FLUSH_PASSED_TO_STREAM

Datatype coercion features

Feature	对应 JsonGenerator.Feature
WRITE_BIGDECIMAL_AS_PLAIN	WRITE_BIGDECIMAL_AS_PLAIN

Schema/Validity support features

Feature	对应 JsonGenerator.Feature
STRICT_DUPLICATE_DETECTION	STRICT_DUPLICATE_DETECTION
IGNORE_UNKNOWN	IGNORE_UNKNOWN

StreamReadFeature

Token reader（parser）特征，不特定于任何特定格式。最终替代非 JSON 特定的 JsonParser.Features

Low-level I/O handling features

Feature	对应 JsonParser.Feature
AUTO_CLOSE_SOURCE	AUTO_CLOSE_SOURCE

Low-level I/O handling features

Feature	对应 JsonParser.Feature
STRICT_DUPLICATE_DETECTION	STRICT_DUPLICATE_DETECTION
IGNORE_UNDEFINED	IGNORE_UNDEFINED

Other

Feature	对应 JsonParser.Feature
INCLUDE_SOURCE_IN_LOCATION	INCLUDE_SOURCE_IN_LOCATION

JsonWriteFeature

Token writer 特征 ，特定于 JSON

Quoting/ecsaping-related features

Feature	默认状态	对应 JsonGenerator.Feature	描述
QUOTE_FIELD_NAMES	true	QUOTE_FIELD_NAMES	是否为字段名添加引号
WRITE_NAN_AS_STRINGS	true	QUOTE_NON_NUMERIC_NUMBERS	对于 NaN 浮点数是否加引号
WRITE_NUMBERS_AS_STRINGS	false	WRITE_NUMBERS_AS_STRINGS	将数字当作字符串输出
ESCAPE_NON_ASCII	false	ESCAPE_NON_ASCII	非ASCII码是否需要转义

JsonReadFeature

Token reader（parser）特征 ，特定于 JSON

Support for non-standard data format constructs: comments

Feature	默认状态	对应 JsonParser.Feature	描述
ALLOW_JAVA_COMMENTS	false	ALLOW_COMMENTS	是否允许注释
ALLOW_YAML_COMMENTS	false	ALLOW_YAML_COMMENTS	是否允许YAML注释

Support for non-standard data format constructs: quoting/escaping

Feature	默认状态	对应 JsonParser.Feature	描述
ALLOW_SINGLE_QUOTES	false	ALLOW_SINGLE_QUOTES	是否允许单引号
ALLOW_UNQUOTED_FIELD_NAMES	false	ALLOW_UNQUOTED_FIELD_NAMES	是否允许出现字段名不带引号
ALLOW_UNESCAPED_CONTROL_CHARS	false	ALLOW_UNQUOTED_CONTROL_CHARS	是否允许出现未加转义的控制字符
ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER	false	ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER	是否允许对所有字符都可加反斜杠转义
ALLOW_LEADING_ZEROS_FOR_NUMBERS	false	ALLOW_NUMERIC_LEADING_ZEROS	是否允许前导的零，例如 000001

Support for non-standard data format constructs: number representations

Feature	默认状态	对应 JsonParser.Feature	描述
ALLOW_LEADING_DECIMAL_POINT_FOR_NUMBERS	false	ALLOW_LEADING_DECIMAL_POINT_FOR_NUMBERS	是否允许前导的小数点，例如 ".04314" 会被解析成 "0.04314"
ALLOW_NON_NUMERIC_NUMBERS	false	ALLOW_NON_NUMERIC_NUMBERS	是否允许 NaN 型的浮点数 （"INF" 当作正无穷、 "-INF" 当作负无穷、 "NaN" 非数字）

Support for non-standard data format constructs: array/value separators

Feature	默认状态	对应 JsonParser.Feature	描述
ALLOW_MISSING_VALUES	false	ALLOW_MISSING_VALUES	是否允许 json 数组中出现缺失值 （例如["value1",,"value3",]将被反序列化为["value1", null, "value3", null] ）
ALLOW_TRAILING_COMMA	false	ALLOW_TRAILING_COMMA	是否允许json尾部有逗号 （例如 {"a": true,} ）

MapperFeature

com.fasterxml.jackson.databind.MapperFeature

General introspection features

Feature	默认状态	描述
USE_ANNOTATIONS	true	是否使用注解自省（检查 JsonProperties 这些）
USE_GETTERS_AS_SETTERS	true	使用 getter 取代 setter 探测属性，这是针对集合类型，可以直接修改集合的属性
PROPAGATE_TRANSIENT_MARKER	false	如何处理 transient 字段，如果 true ，不能访问此属性，若是 false 则不能通过字段访问（还是可以使用 getter 和 setter 访问）

Introspection-based property auto-detection

Feature	默认状态	描述
AUTO_DETECT_CREATORS	true	是否自动检测构造方法或单参且名为 valueOf 的静态工厂方法
AUTO_DETECT_FIELDS	true	是否自动检测字段 （若 true ，则将所有 public 实例字段视为属性）
AUTO_DETECT_GETTERS	true	是否根据标准 Bean 命名约定自动检测常规 getter 方法（不包括 is getter 方法 ）
AUTO_DETECT_IS_GETTERS	true	是否根据标准 Bean 命名约定自动检测 is getter 方法
AUTO_DETECT_SETTERS	true	确定是否根据标准 Bean 命名约定自动检测setter 方法
REQUIRE_SETTERS_FOR_GETTERS	false	是否 getter 方法必须要有对应的 setter 或字段或构造方法参数，才能视为一个属性
ALLOW_FINAL_FIELDS_AS_MUTATORS	true	是否可以逻辑修改 final 成员字段
INFER_PROPERTY_MUTATORS	true	是否能推断属性，(即使用字段和 setter 是不可见的，但 getter 可见即可推断属性)
INFER_CREATOR_FROM_CONSTRUCTOR_PROPERTIES	true	是否自动推断 ConstructorProperties 注解
ALLOW_VOID_VALUED_PROPERTIES	false	是否允许 Void 属性被识别为 null

Access modifier handling

Feature	默认状态	描述
CAN_OVERRIDE_ACCESS_MODIFIERS	true	是否调用 AccessibleObject#setAccessible 设为 true ，将原来不可见的属性，变为可见
OVERRIDE_PUBLIC_ACCESS_MODIFIERS	true	是否对 public 属性调用 AccessibleObject#setAccessible 设为 true

Type-handling features

Feature	默认状态	描述
USE_STATIC_TYPING	false	确定序列化使用的是声明的静态类型还是运行时动态类型，可以使用   JsonSerialize#typing 注解覆盖它
USE_BASE_TYPE_AS_DEFAULT_IMPL	false	反序列化是否使用声明基类作为默认实现，在没有指定 @JsonTypeInfo.defaultImpl 注解的情况下
INFER_BUILDER_TYPE_BINDINGS	true	启用从反序列化的值类型推断构建器类型绑定的功能。这要求值类型上的泛型类型声明与构建器上的泛型类型声明完全匹配：数据绑定不一定检测到不匹配的类型声明

View-related features

Feature	默认状态	描述
DEFAULT_VIEW_INCLUSION	false	没有 JsonView 注解标记的属性是否会被包含在 json 序列化视图中

Generic output features

Feature	默认状态	描述
SORT_PROPERTIES_ALPHABETICALLY	false	按字母表顺序序列化字段（若false，按字段声明的顺序）
SORT_CREATOR_PROPERTIES_FIRST	true	Creator 属性排序在其他属性之前

Name-related features

Feature	默认状态	描述
ACCEPT_CASE_INSENSITIVE_PROPERTIES	false	反序列化属性时不区分大小写
ACCEPT_CASE_INSENSITIVE_ENUMS	false	枚举反序列化不区分大小写
ACCEPT_CASE_INSENSITIVE_VALUES	false	允许解析一些基于文本的枚举的值类型但忽略反序列化值的大小写
USE_WRAPPER_NAME_AS_PROPERTY_NAME	false	使用包装器名称覆盖属性名称， AnnotationIntrospector#findWrapperName
USE_STD_BEAN_NAMING	false	是否强制与 Bean 名称自省严格兼容，以 getURL() 为例，false 是 url ，true 是 URL
ALLOW_EXPLICIT_PROPERTY_RENAMING	false	是否允许 JsonProperty 注解覆盖 PropertyNamingStrategy

Coercion features

Feature	默认状态	描述
ALLOW_COERCION_OF_SCALARS	true	是否允许对简单文本进行标量类型转换 ，即将字符串的 "true" 当作布尔的true ,字符串的 "1.0" 当作 "double" ，不包括日期类型

Other features

Feature	默认状态	描述
IGNORE_DUPLICATE_MODULE_REGISTRATIONS	true	如果模块相同（Module#getTypeId()返回值相同），只有第一次能会真正调用注册方法
IGNORE_MERGE_FOR_UNMERGEABLE	true	在合并不能合并的属性时是否忽略错误
BLOCK_UNSAFE_POLYMORPHIC_BASE_TYPES	false	阻止不安全的基类（如Object Closeable Cloneable AutoCloseable Serializable）
APPLY_DEFAULT_VALUES	true	ObjectReader 是否应用类定义中定义的默认值

SerializationFeature

com.fasterxml.jackson.databind.SerializationFeature

Generic output features

Feature	默认状态	描述
WRAP_ROOT_VALUE	false	反序列化是否有根节点
INDENT_OUTPUT	false	是否使用缩进，格式化输出
FAIL_ON_EMPTY_BEANS	true	对象不含任何字段时报错
FAIL_ON_SELF_REFERENCES	true	自引用报错
WRAP_EXCEPTIONS	true	是否包装异常
FAIL_ON_UNWRAPPED_TYPE_IDENTIFIERS	true	JsonUnwrapped 注解的类有类型信息是否报错
WRITE_SELF_REFERENCES_AS_NULL	false	自引用返回 null

Output life cycle features

Feature	默认状态	描述
CLOSE_CLOSEABLE	false	若对象实现了 Closeable 接口，在序列化后是否调用 close 方法
FLUSH_AFTER_WRITE_VALUE	true	流对象在 writeValue 之后是否强制刷新

Datatype-specific serialization configuration

Feature	默认状态	描述
WRITE_DATES_AS_TIMESTAMPS	true	写日期为时间戳
WRITE_DATE_KEYS_AS_TIMESTAMPS	false	写日期 key 为时间戳
WRITE_DATES_WITH_ZONE_ID	false	写日期包含时区 ID
WRITE_DATES_WITH_CONTEXT_TIME_ZONE	true	timezone/offset 是否包含在时区日期中
WRITE_DURATIONS_AS_TIMESTAMPS	true	写时间段 (durations, periods, ranges) 为时间戳
WRITE_CHAR_ARRAYS_AS_JSON_ARRAYS	false	字符数组输出 json 数组，false 输出字符串
WRITE_ENUMS_USING_TO_STRING	false	写枚举使用 toString
WRITE_ENUMS_USING_INDEX	false	写枚举使用下标
WRITE_ENUM_KEYS_USING_INDEX	false	写枚举 key 使用下标
WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED	false	是否将单个元素的集合展开，（即：去除数组符号"[]"）
WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS	true	将 timestamp 输出为纳秒
ORDER_MAP_ENTRIES_BY_KEYS	false	map 序列化后，是否用 key 对其排序

Other

Feature	默认状态	描述
EAGER_SERIALIZER_FETCH	true	是否急切获取序列化器
USE_EQUALITY_FOR_OBJECT_ID	false	是否使用 objectId 比较是否相等（在 ORM 框架 Hibernate 中有应用）

DeserializationFeature

com.fasterxml.jackson.databind.DeserializationFeature

Value (mostly scalar) conversion features

Feature	默认状态	描述
USE_BIG_DECIMAL_FOR_FLOATS	false	将浮点数读为 BigDecimal
USE_BIG_INTEGER_FOR_INTS	false	将整数读为 BigDecimal
USE_LONG_FOR_INTS	false	将整型读为 Long
USE_JAVA_ARRAY_FOR_JSON_ARRAY	false	无明确类型时，是否将 json 数组反序列化为 java 数组（若是 true，就对应 Object[]  ,反之就是 List<?> ）

Error handling features

Feature	默认状态	描述
FAIL_ON_UNKNOWN_PROPERTIES	true	常用，json 中含 pojo 不存在属性时是否报错
FAIL_ON_NULL_FOR_PRIMITIVES	false	将 null 读为基本数据类型是否报错
FAIL_ON_NUMBERS_FOR_ENUMS	false	用整数读为枚举是否报错
FAIL_ON_INVALID_SUBTYPE	true	找不到合适的子类否报错
FAIL_ON_READING_DUP_TREE_KEY	false	出现重复的 json 字段是否报错
FAIL_ON_IGNORED_PROPERTIES	false	如果 json 中出现了 java 实体字段中已显式标记应当忽略的字段，是否报错
FAIL_ON_UNRESOLVED_OBJECT_IDS	true	如果反序列化发生了不可解析的 ObjectId 是否报错
FAIL_ON_MISSING_CREATOR_PROPERTIES	false	如果缺少 Creator 方法的参数是否报错（false，则使用 null 代替需要的参数
FAIL_ON_NULL_CREATOR_PROPERTIES	false	将 null 绑定到 Creator 方法的参数是否报错
FAIL_ON_MISSING_EXTERNAL_TYPE_ID_PROPERTY	true	注解 JsonTypeInfo.As#EXTERNAL_PROPERTY 的属性缺失，是否报错
FAIL_ON_TRAILING_TOKENS	false	出现尾随 token 是否报错（如果是true,则调用JsonParser#nextToken，检查json的完整性）
WRAP_EXCEPTIONS	true	是否包装反序列化出现的异常

Structural conversion features

Feature	默认状态	描述
ACCEPT_SINGLE_VALUE_AS_ARRAY	false	反序列化时是否将单个值封装成单元素数组
UNWRAP_SINGLE_VALUE_ARRAYS	false	反序列化时是否将单元素数组展开为一个对象
UNWRAP_ROOT_VALUE	false	是否取消根节点的包装

Value conversion features

Feature	默认状态	描述
ACCEPT_EMPTY_STRING_AS_NULL_OBJECT	false	是否将空字符串 ""  当作 null
ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT	false	是否接受将空数组 [] 作为null
ACCEPT_FLOAT_AS_INT	true	是否接受将浮点数作为整数
READ_ENUMS_USING_TO_STRING	false	按照枚举 toString() 方法读取，（false 则按枚举的 name() 方法读取）
READ_UNKNOWN_ENUM_VALUES_AS_NULL	false	读取到未知的枚举当作 null
READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE	false	读取到未知的枚举，将其当作被JsonEnumDefaultValue注解标记的枚举
READ_DATE_TIMESTAMPS_AS_NANOSECONDS	true	将时间戳视为纳秒 (false 则视为毫秒)
ADJUST_DATES_TO_CONTEXT_TIME_ZONE	true	反序列化是否会适应 DeserializationContext#getTimeZone()提供的时区 （此特性仅对 java 8 的时间/日期有效）

Other

Feature	默认状态	描述
EAGER_DESERIALIZER_FETCH	true	是否急切获取反序列化器

源码解读

JacksonFeature 、FormatFeature 、ConfigFeature 三个接口的方法定义没有区别

使用 Builder 创建对象：

JsonMapper jsonMapper = JsonMapper.builder().build();
JsonFactory jsonFactory = JsonFactory.builder().build();

示例

JsonFactoryBuilder jsonFactoryBuilder = new JsonFactoryBuilder();

// 设置允许单引号，否则会报错
jsonFactoryBuilder.configure(JsonReadFeature.ALLOW_SINGLE_QUOTES, true);

JsonFactory factory = jsonFactoryBuilder.build();


StringReader stringReader = new StringReader("{\"a\":'1'}");
JsonParser jsonParser = factory.createParser(stringReader);


JsonToken jsonToken = jsonParser.nextToken();
while (jsonToken != null) {
    System.out.println(jsonToken + " :: " + jsonParser.currentName() + " :: " + jsonParser.getText());
    jsonToken = jsonParser.nextToken();
}
jsonParser.close();