Spring Boot 2.7 + JDK 8 升級(jí)至 Spring Boot 3.4.13 + JDK 17 手冊

前言

Spring Boot 3.x 是 Spring 生態(tài)的重大版本迭代，最低要求 JDK 17，全面擁抱 Jakarta EE 9+（替換原 Java EE）、支持原生鏡像、性能大幅優(yōu)化，且 Spring Boot 2.7 已停止官方維護(hù)。本指南從環(huán)境準(zhǔn)備、依賴升級(jí)、代碼適配、測試驗(yàn)證、問題排查全流程，手把手完成升級(jí)，零門檻落地。

升級(jí)核心目標(biāo)：

  • JDK 8 → OpenJDK 17（LTS 長期支持版）
  • Spring Boot 2.7.x → Spring Boot 3.4.13（最新穩(wěn)定版）
  • 適配 Jakarta EE、移除廢棄 API、兼容新特性

一、升級(jí)前核心前置知識(shí)

  1. 版本強(qiáng)制要求
    • Spring Boot 3.0+ 最低 JDK 17，不支持 JDK 8/11
    • Spring Framework 6.x 配套 Spring Boot 3.x，替換 javax. 包為 jakarta. 包
  2. 兼容性風(fēng)險(xiǎn)點(diǎn)
    • 第三方依賴（MyBatis、Druid、Swagger、FastJSON 等）需升級(jí)適配 3.x
    • 代碼中 javax.servlet/javax.persistence 等包全量替換
    • JDK 9+ 模塊化特性、內(nèi)部 API 封閉可能導(dǎo)致兼容性問題
  3. 升級(jí)順序
    環(huán)境準(zhǔn)備 → 項(xiàng)目配置升級(jí) → 包名替換 → 代碼/依賴適配 → 測試驗(yàn)證 → 上線

二、OpenJDK 17 下載與安裝（官方推薦）

2.1 為什么選擇 OpenJDK 17？

  • JDK 17 是 LTS 長期支持版，穩(wěn)定且免費(fèi)商用
  • Spring Boot 3.4.13 官方推薦 JDK 17+
  • 相比 Oracle JDK，OpenJDK 無版權(quán)風(fēng)險(xiǎn)

2.2 各系統(tǒng) OpenJDK 17 下載地址

操作系統(tǒng) 下載鏈接 說明
Windows OpenJDK 17 Windows 安裝版 推薦 MSI 一鍵安裝
macOS OpenJDK 17 macOS 版 支持 Intel/M 芯片
Linux OpenJDK 17 Linux 版 通用 tar.gz 包

2.3 安裝與環(huán)境配置

Windows 系統(tǒng)

  1. 下載 MSI 安裝包，雙擊運(yùn)行，默認(rèn)路徑安裝即可
  2. 配置環(huán)境變量：
    • 新建 JAVA_HOME：C:\Program Files\Java\jdk-17.x.x
    • 編輯 Path：添加 %JAVA_HOME%\bin
  3. 驗(yàn)證安裝：打開 CMD 輸入 
    java -version
javac -version
    輸出 openjdk version "17.x.x" 即成功

macOS 系統(tǒng)

  1. 下載 DMG 包，拖拽安裝到 /Library/Java/JavaVirtualMachines/
  2. 終端配置環(huán)境變量： 
    # 編輯配置文件
vim ~/.zshrc
# 添加配置
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH
# 生效配置
source ~/.zshrc
  3. 驗(yàn)證：java -version

Linux 系統(tǒng)

  1. 下載 tar.gz 包，解壓到 /usr/local/ 
    tar -zxvf openjdk-17_linux-x64_bin.tar.gz -C /usr/local/
  2. 配置環(huán)境變量： 
    vim /etc/profile
# 末尾添加
export JAVA_HOME=/usr/local/jdk-17
export PATH=$JAVA_HOME/bin:$PATH
# 生效
source /etc/profile
  3. 驗(yàn)證：java -version

三、Maven/Gradle 升級(jí)（必須）

  1. Maven：最低 3.8.6+，推薦 3.9.6
    下載：Maven 3.9.6
  2. Gradle：最低 7.5+，推薦 8.x
  3. 驗(yàn)證版本： 
    mvn -v
gradle -v

四、Spring Boot 項(xiàng)目核心配置升級(jí)

4.1 父工程版本修改（Maven）

打開項(xiàng)目 pom.xml，核心修改 1：

<!-- 原 2.7.x -->
<!-- <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version>
    <relativePath/>
</parent> -->

<!-- 新 3.4.13 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.4.13</version>
    <relativePath/>
</parent>

核心修改 2：指定 JDK 17 編譯

<properties>
    <java.version>17</java.version>
    <!-- 兼容 Maven 編譯 -->
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

4.2 Gradle 配置修改

// 原 2.7.x
// id 'org.springframework.boot' version '2.7.18'

// 新 3.4.13
id 'org.springframework.boot' version '3.4.13'
sourceCompatibility = '17'
targetCompatibility = '17'

五、全量依賴升級(jí)（關(guān)鍵步驟）

Spring Boot 3.x 已內(nèi)置依賴管理，大部分依賴無需指定版本，僅需升級(jí)不兼容的第三方包。

5.1 必改依賴（ Jakarta 適配）

  1. Servlet API（自動(dòng)替換，無需手動(dòng)引入）
  2. MyBatis/MyBatis-Plus 
    <!-- MyBatis -->
<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>
<!-- MyBatis-Plus -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.10</version>
</dependency>
  3. 數(shù)據(jù)庫驅(qū)動(dòng)（MySQL 8+ 推薦） 
    <dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>
  4. Swagger/Knife4j（替換為 SpringDoc）
    Spring Boot 3.x 不支持原 Swagger2，使用 SpringDoc OpenAPI： 
    <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

5.2 移除廢棄依賴

  • 移除 javax.servlet-api
  • 移除 javax.persistence-api
  • 移除舊版 spring-boot-configuration-processor（新版已內(nèi)置）

六、代碼全量適配（最核心改造）

6.1 包名全局替換（javax → jakarta）

這是 Spring Boot 3 最大的變更，所有 javax. 開頭的 EE 包替換為 jakarta.

舊包名（javax） 新包名（jakarta）
javax.servlet.* jakarta.servlet.*
javax.persistence.* jakarta.persistence.*
javax.validation.* jakarta.validation.*
javax.transaction.* jakarta.transaction.*

批量替換方法：

  • IDEA 快捷鍵：Ctrl+Shift+R，全局替換 import javax. → import jakarta.
  • 實(shí)體類、Controller、過濾器、攔截器全量修改

6.2 JDK 17 模塊化適配

JDK 17 封閉了內(nèi)部 API，若出現(xiàn)以下錯(cuò)誤：

module java.base does not "opens java.lang" to unnamed module

解決方案：

  1. 升級(jí)第三方依賴到最新版
  2. 啟動(dòng)參數(shù)添加（臨時(shí)方案，優(yōu)先升級(jí)依賴） 
    <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <jvmArguments>
            --add-opens java.base/java.lang=ALL-UNNAMED
        </jvmArguments>
    </configuration>
</plugin>

6.3 Spring Boot 3.x 廢棄 API 適配

  1. 配置文件：server.tomcat.max-threads 等配置無變更，兼容原有寫法
  2. WebMvcConfigurer：無破壞性變更
  3. RedisTemplate：配置不變，依賴自動(dòng)適配
  4. 定時(shí)任務(wù)：@Scheduled 用法完全兼容

6.4 日志框架適配

Spring Boot 3.x 默認(rèn)使用 Logback，無需額外配置，移除舊版 log4j 依賴。

七、配置文件與啟動(dòng)類適配

  1. 啟動(dòng)類無修改：@SpringBootApplication 用法不變
  2. application.yml/application.properties：
    • 數(shù)據(jù)庫、Redis、端口等配置完全兼容
    • Swagger 替換為 SpringDoc 后，新增配置： 
      springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    path: /swagger-ui.html

八、測試驗(yàn)證

8.1 單元測試升級(jí)

依賴替換：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

測試注解：@SpringBootTest 用法不變，Junit 5 自動(dòng)適配。

8.2 啟動(dòng)驗(yàn)證

  1. 清理 Maven 緩存：mvn clean
  2. 編譯項(xiàng)目：mvn compile
  3. 啟動(dòng)項(xiàng)目，無報(bào)錯(cuò)即基礎(chǔ)適配成功
  4. 訪問接口、Swagger、數(shù)據(jù)庫操作，驗(yàn)證功能正常

九、常見問題與解決方案

問題 1：包沖突 jakarta.servlet 不存在

原因：舊依賴未移除，或第三方包未升級(jí)
解決：執(zhí)行 mvn dependency:tree 排查沖突依賴，升級(jí)至 3.x 適配版

問題 2：JDK 版本錯(cuò)誤：“錯(cuò)誤: 發(fā)行版 17 不支持”

解決：

  • IDEA 設(shè)置：File → Project Structure → SDK 選擇 17
  • Maven/Gradle 配置 java.version=17

問題 3：MyBatis 綁定異常

解決：升級(jí) MyBatis 版本，檢查 mapper.xml 命名空間

問題 4：FastJSON 序列化異常

解決：升級(jí)至 FastJSON 2.x：

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.32</version>
</dependency>

十、升級(jí)后優(yōu)化建議

  1. 啟用虛擬線程（Spring Boot 3.4+ 支持，性能提升） 
    spring:
  threads:
    virtual:
      enabled: true
  2. 使用 Spring Boot 3.x 新特性：AOT 編譯、原生鏡像
  3. 全面替換過時(shí) API，貼合官方最佳實(shí)踐

總結(jié)

本指南覆蓋 OpenJDK 17 下載安裝、Spring Boot 3.4.13 配置升級(jí)、代碼包名替換、依賴適配、問題排查 全流程，按照步驟操作即可完成 Spring Boot 2.7 + JDK 8 到最新版本的平滑升級(jí)。

升級(jí)核心三步：

  1. 安裝 OpenJDK 17，配置開發(fā)環(huán)境
  2. 修改 pom.xml 版本，升級(jí)第三方依賴
  3. 全局替換 javax → jakarta，修復(fù)廢棄 API

升級(jí)后項(xiàng)目將獲得更強(qiáng)性能、更長官方支持、更安全的生態(tài)環(huán)境，為后續(xù)功能迭代奠定基礎(chǔ)。

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容