Jackson用法大全

jackson支持以下格式

Avro, BSON, CBOR, CSV, Smile, (Java) Properties, Protobuf, TOML, XML or YAML;

基礎注解

注解	用法
@JsonProperty	用於屬性，把屬性的名稱序列化時轉換為另外一個名稱。示例：@JsonProperty("birth_date") private Date birthDate
@JsonIgnore	可用於字段、getter/setter、構造函數參數上，作用相同，都會對相應的字段產生影響。使相應字段不參與序列化和反序列化。
@JsonIgnoreProperties	該注解是類注解，使得相應字段不參與序列化和反序列化。eg:@JsonIgnoreProperties({"password","id"}) public class Person
@JsonFormat	用於屬性或者方法，把屬性的格式序列化時轉換成指定的格式。示例：@JsonFormat(timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm") public Date getBirthDate()
@JsonPropertyOrder	該注解是類注解,和 @JsonProperty的index屬性類似，指定屬性在序列化時 json 中的順序 ， 示例：@JsonPropertyOrder({ "birth_Date", "name" }) public class Person
@JsonCreator	用於構造方法，和 @JsonProperty 配合使用，適用有參數的構造方法。示例：@JsonCreator public Person(@JsonProperty("name")String name) {…}
@JsonAnySetter	用於屬性或者方法，設置未反序列化的屬性名和值作為鍵值存儲到 map 中 @JsonAnySetter public void set(String key, Object value) { map.put(key, value); }
@JsonAnyGetter	應用於屬性或方法，獲取所有未序列化的屬性 public Map<String, Object> any() { return map; }
@JsonSetter	應用於屬性或方法，指定反序列化的字段名 @JsonSetter("_id") public String setId(String id) { return this.id=id; }
@JsonGetter	應用於方法或字段，指定序列化的字段名 @JsonGetter("_id") public String getId() { return id; }
@JsonNaming	類注解。序列化的時候該注解可將駝峰命名的字段名轉換為下划線分隔的小寫字母命名方式。反序列化的時候可以將下划線分隔的小寫字母轉換為駝峰命名的字段名。示例：@JsonNaming(PropertyNamingStrategy.SnakeCaseStrategy.class)
@JsonRootName	類注解。需開啟mapper.enable(SerializationFeature.WRAP_ROOT_VALUE)，用於序列化時輸出帶有根屬性名稱的JSON串，形式如 {"root_name":{"id":1,"name":"zhangsan"}}。
@JsonAutoDetect	指定屬性（反）序列化范圍
@JsonIgnoreType	將忽略這個類型的（反）序列化
@JsonInclude	對空值如何序列化
@JsonPropertyDescription	json的schema描述
@JsonUnwrapped	將其屬性上拉一個層級展開
@JsonView	不同接口下返回不同的屬性 eg：@JsonView的使用
@JacksonInject	json字段有一些缺少的屬性，抓換成實體類的時候沒有的屬性將為null,但是我們在某些需求當中需要將為null的屬性都設置為默認
@JsonEnumDefaultValue	反序列化時未知時的枚舉值
@JsonRawValue	使用原始值,而不會進行轉義 eg:"content":"Test content",而不是\"content\":\"Test content\"
@JsonValue	最多能用於類的一個屬性(多個屬性應用此注解將拋出異常)，並將此屬性上拉一個層級展開，其他字段不參與（反）序列化
@JsonKey	最多能用於類的一個屬性(多個屬性應用此注解將拋出異常)，這個類型對象作為Map數據結構的Key時，標記此注解的屬性值將作為json字符串的字段名
@JsonFilter	應用於屬性， 過濾屬性 eg:@JsonFilter("non-pwd") private char[] password = new char[]{'0', '\u0343', '&'}; mapper.setFilterProvider(new SimpleFilterProvider().addFilter("non-pwd", SimpleBeanPropertyFilter.serializeAllExcept("password")));
@JsonAlias	應用於屬性，反序列化時多個候選字段名能夠映射到同一個屬性上
@JsonMerge	應用於屬性，反序列化時集合類型屬性時，將Json中的元素與字段中的默認元素融合 eg:@JsonMerge private List<String> hobbies = new ArrayList<>(Collections.singletonList("籃球"));

多態類型處理注解

• @JsonSubTypes: 類注解 類注解用於指示注解類型的子類型； 使用邏輯類型名稱（而不是類名稱）指定反序列化多態類型
• @JsonTypeId: 類/屬性/方法注解 用於指示屬性值應該用作對象的 Type Id ，而不是使用類名或外部類型名。
• @JsonTypeInfo: 類/屬性注解 用於指示序列化中包含哪些類型信息以及如何包含在內的詳細信息。
• @JsonTypeName: 類注解 用於定義用於注釋類的邏輯類型名稱；類型名稱可以用作Type Id（取決於@JsonTypeInfo的設置） Java Jackson @JsonTypeInfo 多態類型處理

對象雙向引用及對象ID

• @JsonManagedReference，@JsonBackReference: 這對注解，用於指示和處理用一對匹配屬性表示的父/子關系 (雙向引用將導致無限遞歸)
• @JsonIdentityInfo: 類/屬性注解 用於指示在序列化/反序列化值時要使用“對象標識id”，以便可以正確反序列化對單個 Java 對象的多個引用。

SpringBoot Jackson 配置大全

spring:
  jackson:
    # 設置屬性命名策略,對應jackson下PropertyNamingStrategy中的常量值，SNAKE_CASE-返回的json駝峰式轉下划線，json body下划線傳到后端自動轉駝峰式
    property-naming-strategy: SNAKE_CASE
    # 全局設置@JsonFormat的格式pattern
    date-format: yyyy-MM-dd HH:mm:ss
    # 當地時區
    locale: zh_CN
    # 設置全局時區
    time-zone: GMT+8
    # 常用，全局設置pojo或被@JsonInclude注解的屬性的序列化方式
    default-property-inclusion: NON_NULL #不為空的屬性才會序列化,具體屬性可看JsonInclude.Include
    # 常規默認,枚舉類SerializationFeature中的枚舉屬性為key，值為boolean設置jackson序列化特性,具體key請看SerializationFeature源碼
    visibility:
      #屬性序列化的可見范圍
      getter: non_private
      #屬性反序列化的可見范圍
      setter: protected_and_public
      #靜態工廠方法的反序列化
      CREATOR: public_only
      #字段
      FIELD: public_only
      #布爾的序列化
      IS_GETTER: public_only
      #所有類型(即getter setter FIELD）不受影響,無意義
      NONE: public_only
      #所有類型(即getter setter FIELD）都受其影響（慎用）
      ALL: public_only
    serialization:
      #反序列化是否有根節點
      WRAP_ROOT_VALUE: false
      #是否使用縮進，格式化輸出
      INDENT_OUTPUT: false
      FAIL_ON_EMPTY_BEANS: true # 對象不含任何字段時是否報錯，默認true
      FAIL_ON_SELF_REFERENCES: true #循環引用報錯
      WRAP_EXCEPTIONS: true #是否包裝異常
      FAIL_ON_UNWRAPPED_TYPE_IDENTIFIERS: true #JsonUnwrapped標記的類有類型信息是否報錯
      WRITE_SELF_REFERENCES_AS_NULL: false #循環引用返回null
      CLOSE_CLOSEABLE: true #若對象實現了CLOSEABLE接口，在序列化后是否調用Close方法
      FLUSH_AFTER_WRITE_VALUE: false #流對象序列化之后是否強制刷新
      WRITE_DATES_AS_TIMESTAMPS: true # 返回的java.util.date轉換成時間戳
      WRITE_DATES_WITH_ZONE_ID: true #2011-12-03T10:15:30+01:00[Europe/Paris]帶時區id
      WRITE_DURATIONS_AS_TIMESTAMPS: true #將DURATIONS轉換成時間戳
      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_NULL_MAP_VALUES: false #是否輸出map中的空entry(此特性已過期，請使用JsonInclude注解)
      WRITE_EMPTY_JSON_ARRAYS: true # 對象屬性值是空集合是否輸出空json數組
      WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED: false #是否將單個元素的集合展開，（即：去除數組符號"[]"）
      WRITE_BIGDECIMAL_AS_PLAIN: false #是否調用BigDecimal#toPlainString()輸出
      WRITE_DATE_TIMESTAMPS_AS_NANOSECONDS: #將timestamp輸出為納秒
      ORDER_MAP_ENTRIES_BY_KEYS: false #map序列化后，是否用key對其排序
      EAGER_SERIALIZER_FETCH: true #是否馬上獲取序列化器
      USE_EQUALITY_FOR_OBJECT_ID: false #是否使用objectId比較是否相等（在ORM框架Hibernate中有應用）

    # 枚舉類DeserializationFeature中的枚舉屬性為key，值為boolean設置jackson反序列化特性,具體key請看DeserializationFeature源碼
    deserialization:
      USE_BIG_DECIMAL_FOR_FLOATS: false #將浮點數反序列化為BIG_DECIMAL
      USE_BIG_INTEGER_FOR_INTS: false #將整數反序列化為BIG_INTEGER
      USE_LONG_FOR_INTS: false #將整型反序列化為長整
      USE_JAVA_ARRAY_FOR_JSON_ARRAY: false #無明確類型時，是否將json數組反序列化為java數組（若是true，就對應Object[] ,反之就是List<?>）
      FAIL_ON_UNKNOWN_PROPERTIES: false # 常用,json中含pojo不存在屬性時是否失敗報錯,默認true
      FAIL_ON_NULL_FOR_PRIMITIVES: false #將null反序列化為基本數據類型是否報錯
      FAIL_ON_NUMBERS_FOR_ENUMS: false #用整數反序列化為枚舉是否報錯
      FAIL_ON_INVALID_SUBTYPE: false #找不至合適的子類否報錯 （如注解JsonTypeInfo指定的子類型）
      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 #如果缺少靜態工廠方法的參數是否報錯（false,則使用null代替需要的參數）
      FAIL_ON_NULL_CREATOR_PROPERTIES: false #將空值綁定到構造方法或靜態工廠方法的參數是否報錯
      FAIL_ON_MISSING_EXTERNAL_TYPE_ID_PROPERTY: false #注解JsonTypeInfo.As#EXTERNAL_PROPERTY標記的屬性缺失，是否報錯
      FAIL_ON_TRAILING_TOKENS: false #出現尾隨令牌是否報錯（如果是true,則調用JsonParser#nextToken，檢查json的完整性）
      WRAP_EXCEPTIONS: true #是否包裝反序列化出現的異常
      ACCEPT_SINGLE_VALUE_AS_ARRAY: true #反序列化時是否將一個對象封裝成單元素數組
      UNWRAP_SINGLE_VALUE_ARRAYS: false #反序列化時是否將單元素數組展開為一個對象
      UNWRAP_ROOT_VALUE: false #是否將取消根節點的包裝
      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()提供的時區 （此特性僅對java8的時間/日期有效）
      EAGER_DESERIALIZER_FETCH: true  #是否馬上獲取反序列化器
    # 枚舉類MapperFeature中的枚舉屬性為key，值為boolean設置jackson ObjectMapper特性
    # ObjectMapper在jackson中負責json的讀寫、json與pojo的互轉、json tree的互轉,具體特性請看MapperFeature,常規默認即可
    mapper:
      USE_ANNOTATIONS: true #是否使用注解自省（檢查JsonProperties這些）
      # 使用getter取代setter探測屬性，這是針對集合類型，可以直接修改集合的屬性
      USE_GETTERS_AS_SETTERS: true #默認false
      PROPAGATE_TRANSIENT_MARKER: false #如何處理transient字段，如果true(不能訪問此屬性) ，若是false則不能通過字段訪問（還是可以使用getter和setter訪問）
      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: false # 確定是否根據標准 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注解
      CAN_OVERRIDE_ACCESS_MODIFIERS: true #調用AccessibleObject#setAccessible設為true .將原來不可見的屬性，變為可見
      OVERRIDE_PUBLIC_ACCESS_MODIFIERS: true #對所有的屬性調用AccessibleObject#setAccessible設為true .（即使用是公共的）
      USE_STATIC_TYPING: false #序列化使用聲明的靜態類型還是動態類型  JsonSerialize#typing注解可覆蓋它
      USE_BASE_TYPE_AS_DEFAULT_IMPL: false # 反序列化是否使用基本類作為默實現 @JsonTypeInfo.defaultImpl
      DEFAULT_VIEW_INCLUSION: true #沒有JsonView注解標記的屬性是否會被包含在json序列化視圖中
      SORT_PROPERTIES_ALPHABETICALLY: false #按字母表順序序列化字段（若false，按字段聲明的順序）
      ACCEPT_CASE_INSENSITIVE_PROPERTIES: false #反序列化屬性時不區分大小寫 （true時，會影響性能）
      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()）變成URL （jackson默認false, url）
      ALLOW_EXPLICIT_PROPERTY_RENAMING: false #是否允許JsonProperty注解覆蓋PropertyNamingStrategy
      ALLOW_COERCION_OF_SCALARS: true # 是否允許強制使用文本標題 ，即將字符串的"true"當作布爾的true ,字符串的"1.0"當作"double"
      IGNORE_DUPLICATE_MODULE_REGISTRATIONS: true #如果模塊相同（Module#getTypeId()返回值相同），只有第一次能會真正調用注冊方法
      IGNORE_MERGE_FOR_UNMERGEABLE: true #在合並不能合並的屬性時是否忽略錯誤
      BLOCK_UNSAFE_POLYMORPHIC_BASE_TYPES: false #阻止不安全的基類（如Object Closeable Cloneable AutoCloseable Serializable）
    parser:
      AUTO_CLOSE_SOURCE: true #是否自動關閉不屬於解析器的底層輸入流
      ALLOW_COMMENTS: false #是否允許json注解（Json規范是不能加注釋的，但這里可以配置）
      ALLOW_YAML_COMMENTS: false #是否允許出現yaml注釋
      ALLOW_UNQUOTED_FIELD_NAMES: false #是否允許出現字段名不帶引號
      ALLOW_SINGLE_QUOTES: false # 是否允許出現單引號,默認false
      ALLOW_UNQUOTED_CONTROL_CHARS: false #是否允許出現未加轉義的控制字符
      ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER: false #是否允許對所有字符都可加反斜杠轉義
      ALLOW_NUMERIC_LEADING_ZEROS: false #是否允許前導的零 000001
      ALLOW_LEADING_DECIMAL_POINT_FOR_NUMBERS: false #是否允許前導的小點數 如 ".04314"會被解析成"0.04314"
      ALLOW_NON_NUMERIC_NUMBERS: false #是否允許NaN型的浮點數 （"INF"當作正無窮  "-INF"當作負無窮 "NaN"非數字，類型於除數為0）
      ALLOW_MISSING_VALUES: false # 是否允許json數組中出現缺失值 （如["value1",,"value3",]將被反序列化為["value1", null, "value3", null]）
      ALLOW_TRAILING_COMMA: false # 是否允許json尾部有逗號 （如{"a": true,}）
      STRICT_DUPLICATE_DETECTION: false #是否啟用嚴格的字段名重復檢查（開啟后會增加20-30%左右的性能開銷）
      IGNORE_UNDEFINED: false #屬性定義未找到是否報錯（這不是針對json,是針對Avro, protobuf等需要Schema的格式）
      INCLUDE_SOURCE_IN_LOCATION: false #是否包含其源信息（如總字節數，總字符數 行號 列號 ）
    generator:
      AUTO_CLOSE_TARGET: true #是否自動關閉不屬於生成器的底層輸出流
      AUTO_CLOSE_JSON_CONTENT: true #是否自動補全json(當有不匹配的JsonToken#START_ARRAY JsonToken#START_OBJECT時)
      FLUSH_PASSED_TO_STREAM: true #是否刷新generator
      QUOTE_FIELD_NAMES: true #是否為字段名添加引號
      QUOTE_NON_NUMERIC_NUMBERS: true #對於NaN浮點數是否加引號
      ESCAPE_NON_ASCII: false #非ASCII碼是否需要轉義
      WRITE_NUMBERS_AS_STRINGS: false #將數字當作字符串輸出 （防止Javascript長度限制被截斷）
      WRITE_BIGDECIMAL_AS_PLAIN: false #按BigDecimal的toPlainString()輸出
      STRICT_DUPLICATE_DETECTION: false #是否啟用嚴格的字段名重復檢查
      IGNORE_UNKNOWN: false #屬性定義未找到是否報錯（這不是針對json,是針對Avro, protobuf等需要Schema的格式）