一、核心要點(diǎn)（必掌握，遷移基礎(chǔ)）

1. 環(huán)境基線升級(jí)： 最低支持 JDK 17（2.x 為 JDK 8），項(xiàng)目需先完成 JDK 升級(jí)適配。

2. 包名與依賴變更：

• Maven groupId：com.fasterxml.jackson → tools.jackson（jackson-annotations 除外，仍用 2.x 版本）Java 導(dǎo)入包：
• com.fasterxml.jackson.xxx → tools.jackson.xxx（com.fasterxml.jackson.annotation 保留不變）

3. 核心 API 不可變性： ObjectMapper（及子類）、JsonFactory（及子類）變?yōu)橥耆豢勺?，必須通過 Builder 模式構(gòu)建（不再支持直接 set 配置）。

JsonMapper m=JsonMapper.builder().build();
JsonFactory f = JsonFactory.builder().build();

4 .異常體系重構(gòu)： 所有異常改為非檢查型（繼承 RuntimeException），核心異常類重命名（如 JsonProcessingException → JacksonException）。 5. 格式綁定強(qiáng)制化： 必須使用格式對(duì)齊的 ObjectMapper 子類（如 JsonMapper、YAMLMapper、XmlMapper），禁止 new ObjectMapper(new YAMLFactory()) 寫法。 6. Java 8 模塊內(nèi)置： jackson-module-parameter-names、jackson-datatype-jdk8、jackson-datatype-jsr310 已整合到 jackson-databind，無需單獨(dú)依賴。

二、關(guān)鍵變更（影響代碼改造）

1. 內(nèi)容移除

• 版本標(biāo)記為 @Deprecated 的方法、字段、類全部刪除（ 參考 2.20 javadoc 替換為替代方案）。
• 移除模塊 jackson-module-jsonSchema 、jackson-datatype-hibernateX。
• 移除功能：格式自動(dòng)檢測(cè)（DataFormatDetector 等相關(guān)類）、ObjectMapper.canSerialize()/canDeserialize() 方法。
• JsonParser canWriteBinaryNatively(), canWriteFormattedNumbers() 分別替為  StreamWriteCapability.CAN_WRITE_BINARY_NATIVELY  /  StreamWriteCapability.CAN_WRITE_FORMATTED_NUMBERS
• JsonFactory getCodec() 、 setCodec() 被移除
• com.fasterxml.jackson.databind.MappingJsonFactory  被移除
• com.fasterxml.jackson.core.ObjectCodec 被移除，替換為 2 個(gè)獨(dú)立的接口：  tools.jackson.core.ObjectReadContext（實(shí)現(xiàn)類：DeserializationContext） ， tools.jackson.core.ObjectWriteContext（實(shí)現(xiàn)類： SerializationContext ）
• tools.jackson.databind.jsontype.impl.LaissezFaireSubTypeValidator 已不再公開。請(qǐng)使用  BasicPolymorphicTypeValidator.builder()
• JsonGenerator.setPrettyPrinter() 被移除
• request payload 能力被移除
• BufferRecyclers.SYSTEM_PROPERTY_TRACK_REUSABLE_BUFFERS 被移除
• TokenStreamFactory.Feature.USE_THREAD_LOCAL_FOR_BUFFER_RECYCLING 被移除
• 在 Jackson 2.x 的 JsonFactory 類中，接受 URL 參數(shù)的工廠方法將被移除

2. 類與方法重命名（高頻變更）

3. 配置默認(rèn)值變更（易引發(fā)行為差異）

4. 功能拆分與遷移

• 流式 API 特性拆分： JsonParser.Feature → StreamReadFeature（通用）+ JsonReadFeature（JSON 專用）； JsonGenerator.Feature → StreamWriteFeature + JsonWriteFeature（其他格式如 XML/YAML 同理）。
• 遷移配置：

三、注意事項(xiàng)（避坑關(guān)鍵）

1. 依賴管理建議

優(yōu)先使用 jackson-bom 統(tǒng)一版本（避免 jackson-annotations 版本沖突）：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>tools.jackson</groupId>
      <artifactId>jackson-bom</artifactId>
      <version>3.0.0</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

無需手動(dòng)引入 jackson-core 和 jackson-annotations，jackson-databind 會(huì)自動(dòng)傳遞依賴。

2. 代碼改造注意

ObjectMapper 構(gòu)建： 必須用 Builder 模式，示例：

// 3.x 正確寫法
JsonMapper mapper = JsonMapper.builder()
    .enable(JsonWriteFeature.ESCAPE_NON_ASCII)
    .changeDefaultPropertyInclusion(incl -> incl.withValueInclusion(JsonInclude.Include.NON_NULL))
    .build();

// 重新配置已有 mapper（不可變對(duì)象無法直接修改）
JsonMapper newMapper = mapper.rebuild()
    .enable(SerializationFeature.INDENT_OUTPUT)
    .build();

泛型類型校驗(yàn)： LaissezFaireSubTypeValidator 不再公開，需用 BasicPolymorphicTypeValidator 構(gòu)建：

BasicPolymorphicTypeValidator validator = BasicPolymorphicTypeValidator.builder()
    .allowIfSubType("com.example")
    .build();

日期格式/時(shí)區(qū)配置： UTC 的默認(rèn)形式現(xiàn)在尾部是 Z ，而不是像 2.x 版本中的  +00 。

//錯(cuò)誤的方式
mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"));
mapper.setTimeZone(TimeZone.getDefault());

//正確的方式
ObjectMapper mapper = JsonMapper.builder()
.defaultDateFormat(new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"))
.defaultTimeZone(TimeZone.getDefault())
.build();

序列化配置：

//錯(cuò)誤的方式
mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);

//正確的方式
ObjectMapper mapper = JsonMapper.builder()
  .changeDefaultPropertyInclusion(incl -> incl.withValueInclusion(JsonInclude.Include.NON_NULL))
  .changeDefaultPropertyInclusion(incl -> incl.withContentInclusion(JsonInclude.Include.NON_NULL))
  .build();

可見性配置： MapperFeature.AUTO_DETECT_XXX 已移除，需通過 changeDefaultVisibility 配置：

//錯(cuò)誤的方式
mapper.disable(MapperFeature.AUTO_DETECT_FIELDS);

//正確的方式
ObjectMapper mapper = JsonMapper.builder()
    .changeDefaultVisibility(vc ->
        vc.withFieldVisibility(JsonAutoDetect.Visibility.NONE))
.build();

包含類型信息配置：

//錯(cuò)誤的方式

mapper.activateDefaultTypingAsProperty(LaissezFaireSubTypeValidator.instance,
    ObjectMapper.DefaultTyping.NON_CONCRETE_AND_ARRAYS,
    "@class");
    
 //正確的方式
 
var typeValidator = BasicPolymorphicTypeValidator.builder()
        .allowIfSubType("my.package.base.name.")
        .allowIfSubType("java.util.concurrent.")
        .allowIfSubTypeIsArray()
        // ...
        .build();
        
ObjectMapper mapper = JsonMapper.builder()
    .activateDefaultTypingAsProperty(typeValidator, DefaultTyping.NON_CONCRETE_AND_ARRAYS, "@class")
.build();
   

JsonNode 處理中的 DecimalNode 創(chuàng)建策略 通過 JsonNodeFactory 創(chuàng)建 DecimalNode 時(shí)，舊行為：可能會(huì)自動(dòng)截?cái)辔搽S零（如 1.200 → 1.2）新行為：默認(rèn)不截?cái)辔搽S零，保持最小限度修剪

// 示例：不同的表示方式
BigDecimal value1 = new BigDecimal("1.200");  // 三位小數(shù)
BigDecimal value2 = new BigDecimal("1.2");     // 一位小數(shù)

// 新行為：DecimalNode會(huì)保持原始精度
// value1 仍會(huì)表示為 "1.200"
// value2 仍會(huì)表示為 "1.2"

Month 序列化/反序列化行為變更

// java.time.Month 枚舉
public enum Month {
    JANUARY,    // 1
    FEBRUARY,   // 2
    // ... 
    DECEMBER    // 12
}

// Jackson 2.x 序列化結(jié)果（默認(rèn)）
{"month": "JANUARY"}  // 或使用索引：{"month": 0}

// Jackson 3.x 序列化結(jié)果（默認(rèn)）
{"month": 1}  // 直接使用 Month 的數(shù)值（1-12）

3. 性能優(yōu)化點(diǎn)

關(guān)閉末尾字符校驗(yàn)： 若輸入數(shù)據(jù)可信，可禁用 FAIL_ON_TRAILING_TOKENS 減少開銷：

JsonMapper.builder().disable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS).build();

緩沖區(qū)回收配置： 3.x 默認(rèn)使用雙端隊(duì)列回收池，高并發(fā)場(chǎng)景可切換回 2.x 的 ThreadLocal 池：

JsonFactory factory = JsonFactory.builder() .recyclerPool(JsonRecyclerPools.threadLocalPool()) .build();
JsonMapper mapper = JsonMapper.builder(factory).build();

4. 兼容性適配

• 若需保留 2.x 部分默認(rèn)行為，可使用 JsonMapper.builderWithJackson2Defaults() 快速遷移（但無法覆蓋所有配置）。
• 單元測(cè)試需重點(diǎn)檢查：字段序列化順序、日期格式、未知字段處理、枚舉序列化方式等受默認(rèn)配置變更影響的場(chǎng)景。

5. 生態(tài)支持

• Spring 已在 2025.10 版本支持 Jackson 3.x（需升級(jí) Spring 相關(guān)依賴）。
• 可使用 OpenRewrite 工具自動(dòng)完成部分遷移（參考：docs.openrewrite.org/recipes/jav…

總結(jié)

Jackson 3.x 遷移的核心是 “環(huán)境升級(jí) + 依賴變更 + Builder 模式適配 + 廢棄 API 替換”，關(guān)鍵在于處理包名、不可變對(duì)象構(gòu)建和默認(rèn)配置變更帶來的兼容性問題。建議先升級(jí) JDK 17，再通過依賴替換、代碼批量改造（重點(diǎn)是 ObjectMapper 構(gòu)建和異常處理）、單元測(cè)試驗(yàn)證逐步完成遷移，優(yōu)先使用官方提供的 Builder 方法和兼容工具減少手動(dòng)改造成本。

到此這篇關(guān)于Jackson3遷移核心注意點(diǎn)總結(jié)大全的文章就介紹到這了,更多相關(guān)Jackson3遷移注意點(diǎn)內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論