前言

Spring Boot 4.0于2025年11月20日正式發(fā)布，是繼2.x到3.x之后框架的又一次重大重構。本次升級將單體自動配置拆分為47個輕量模塊、原生集成JSpecify空安全校驗、內(nèi)置API版本控制能力，同時基于Spring Framework 7.0打造，帶來了更優(yōu)的性能和開發(fā)體驗。Spring Boot 3.5.x的支持將持續(xù)至2026年11月，為開發(fā)者預留了充足的遷移時間，而新特性帶來的性能提升和開發(fā)效率優(yōu)化，讓遷移具備極高的實際價值。

本文基于生產(chǎn)環(huán)境服務的遷移實踐，從版本前置升級、環(huán)境檢查、核心配置修改、空安全修復、API版本控制配置等方面，提供可落地的分步遷移指南，同時梳理遷移過程中的常見問題與解決方案，幫你平穩(wěn)完成從Spring Boot 3.5到4.0的升級。

一、Spring Boot 4.0 核心變更與升級價值

Spring Boot 4.0的核心更新圍繞模塊化、空安全、原生功能增強展開，最低要求Java 17（推薦Java 21 LTS），Kotlin項目需升級至2.2及以上版本，核心變更及升級帶來的實際價值如下：

1.1 核心變更

1. 自動配置模塊化：將原6.2MB的spring-boot-autoconfigure單體JAR拆分為47個專屬輕量模塊，引入spring-boot-starter-web僅加載WebMVC配置，不再包含批處理、MongoDB等無關配置；
2. 空安全體系升級：使用JSpecify 1.0替代原org.springframework.lang的空注解，支持編譯期空安全校驗，提前規(guī)避NPE問題；
3. 原生API版本控制：無需自定義RequestMappingHandlerMapping或路徑拼接，通過注解和配置即可實現(xiàn)Header/路徑式API版本控制；
4. 聲明式HTTP客戶端：內(nèi)置聲明式HTTP客戶端，無需依賴Feign等第三方庫；
5. 可觀測性增強：集成Micrometer 2.0，支持SSL健康檢查，監(jiān)控能力更完善；
6. 依賴與測試調(diào)整：移除MockitoTestExecutionListener，需改用MockitoExtension；精簡spring-boot-starter-parent結構；核心消息抽象遷移至spring-messaging模塊。

1.2 實際升級價值

基于生產(chǎn)服務的遷移實測，Spring Boot 4.0相比3.5.x帶來了顯著的性能和開發(fā)體驗提升：

• 鏡像體積減少19%：從387MB降至312MB，降低容器部署的存儲和網(wǎng)絡成本；
• 啟動時間縮短33%：從4.2秒降至2.8秒，提升服務彈性擴縮容效率；
• 消除冗余代碼：原生API版本控制可移除200行左右的自定義路由代碼；
• 提前規(guī)避BUG：編譯期空安全校驗可發(fā)現(xiàn)潛在的空指針問題，減少生產(chǎn)環(huán)境故障；
• 依賴更簡潔：模塊化的自動配置讓依賴圖譜更清晰，減少無用依賴的加載。

二、遷移前置準備

2.1 版本前置升級：先升級至3.5.x最新版

禁止直接從3.3及以下版本跳級至4.0，需先升級到Spring Boot 3.5.x的最新版本（截至2025年12月為3.5.6），該步驟可提前暴露棄用警告，確保依賴的兼容性。

Maven配置修改

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.5.6</version>
</parent>

Gradle配置修改

plugins {
  id 'org.springframework.boot' version '3.5.6'
}

升級后執(zhí)行測試，修復所有失敗用例：

# Maven
./mvnw clean test
# Gradle
./gradlew clean test

關鍵修復：3.4開始棄用MockitoTestExecutionListener，4.0直接移除，若測試類使用@Mock/@Captor但未引入MockitoExtension，會出現(xiàn)Mock對象為null的問題，需在測試類添加：

import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.junit.jupiter.MockitoExtension;

@ExtendWith(MockitoExtension.class)
class MyServiceTest {
  @Mock
  private MyRepository repo;
  // 測試邏輯
}

2.2 檢查并升級Java/Kotlin版本

Spring Boot 4.0要求Java 17及以上（推薦Java 21 LTS），Kotlin項目需Kotlin 2.2及以上，先檢查當前版本：

java -version

Java 21 安裝（主流系統(tǒng)）

• macOS（Homebrew）：

  brew install openjdk@21

• Ubuntu：

  sudo apt update
  sudo apt install openjdk-21-jdk

構建文件中指定Java版本

• Maven（pom.xml）：

  <properties>
    <java.version>21</java.version>
  </properties>

• Gradle（build.gradle）：

  java {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
  }

Kotlin版本升級（pom.xml）

<kotlin.version>2.2.0</kotlin.version>

修改后重新構建并測試，確?；A環(huán)境無問題。

三、正式升級至Spring Boot 4.0.0

完成前置準備后，將Spring Boot版本正式修改為4.0.0，這一步是遷移的核心，會出現(xiàn)依賴和編譯相關的錯誤，需逐一修復。

3.1 修改構建文件版本

Maven

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>4.0.0</version>
</parent>

Gradle

plugins {
  id 'org.springframework.boot' version '4.0.0'
}

3.2 執(zhí)行構建并修復依賴缺失問題

# Maven
./mvnw clean package
# Gradle
./gradlew clean build

最常見錯誤：模塊化拆分后，直接導入自動配置類但未引入對應starter的，會出現(xiàn)類缺失，需添加專屬starter依賴。
示例：使用Spring Data MongoDB需添加：

<!-- 非響應式 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>
<!-- 響應式 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-mongodb-reactive</artifactId>
</dependency>

若未使用starter，需手動添加對應的自動配置模塊（模塊列表參考Spring Boot 4.0官方遷移指南），例如使用TestRestTemplate需添加：

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-autoconfigure-web</artifactId>
</dependency>

四、修復JSpecify空安全警告

Spring Boot 4.0全面采用JSpecify 1.0的空注解（org.jspecify.annotations），替代原Spring的空注解（org.springframework.lang），支持編譯期空安全校驗，是本次升級的核心重點之一。

4.1 添加JSpecify依賴

<dependency>
  <groupId>org.jspecify</groupId>
  <artifactId>jspecify</artifactId>
  <version>1.0.0</version>
</dependency>

4.2 開啟包級別的空安全標記

創(chuàng)建package-info.java文件，標記當前包為默認非空，僅顯式標注@Nullable的對象可為空，實現(xiàn)全局空安全約束：

@NullMarked
package com.example.myapp;

import org.jspecify.annotations.NullMarked;

4.3 修復具體的空安全警告

添加依賴和標記后，IDEA 2025.3+/Eclipse（Spring Tools）會在編譯期提示空安全警告，核心修復場景為未處理可空對象的空值情況。

典型場景：倉庫查詢結果未判空

原代碼（有警告）：

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
  // findById返回@Nullable User/Optional<User>，直接返回會觸發(fā)警告
  return userRepository.findById(id);
}

修復后代碼：

import org.springframework.http.HttpStatus;
import org.springframework.web.server.ResponseStatusException;

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
  // 方式1：Optional判空
  return userRepository.findById(id)
    .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
  // 方式2：直接判空
  /*
  User user = userRepository.findById(id);
  if (user == null) {
    throw new ResponseStatusException(HttpStatus.NOT_FOUND);
  }
  return user;
  */
}

4.4 （可選）構建期強制空安全校驗

若需要在CI/構建階段強制校驗空安全，可集成NullAway，拒絕空安全違規(guī)的代碼構建（需Java 21+），Maven配置示例：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <compilerArgs>
      <arg>-XDaddTypeAnnotationsToSymbol=true</arg>
      <arg>-Xplugin:NullAway</arg>
    </compilerArgs>
    <annotationProcessorPaths>
      <path>
        <groupId>com.uber.nullaway</groupId>
        <artifactId>nullaway</artifactId>
        <version>0.10.12</version>
      </path>
    </annotationProcessorPaths>
  </configuration>
</plugin>

執(zhí)行mvn compile，若存在空安全違規(guī)，構建會直接失敗。

五、配置原生API版本控制

Spring Boot 4.0內(nèi)置API版本控制能力，無需自定義代碼，支持Header式和路徑式兩種方式，徹底替代傳統(tǒng)的路徑拼接/自定義處理器方案。

5.1 核心配置：選擇版本控制方式

在application.properties/application.yml中配置版本控制的核心規(guī)則，二選一即可。

方式1：Header式版本控制（推薦）

通過請求頭傳遞API版本，保持URL整潔，適合內(nèi)部服務/前后端分離項目：

# 自定義頭名稱為API-Version
spring.mvc.apiversion.use.header=API-Version

方式2：路徑式版本控制

通過URL路徑段傳遞API版本，適合瀏覽器端/無請求頭控制的場景：

# 數(shù)字1表示版本為URL的第2個路徑段（索引從0開始）
spring.mvc.apiversion.use.path-segment=1
# 示例：/api/v1.2/users → 版本為v1.2

5.2 接口中添加版本注解

在@GetMapping/@PostMapping等注解中通過version屬性指定接口版本，支持多版本接口共存。

Header式版本控制示例

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;

@RestController
@RequestMapping("/api/users")
public class UserController {

  // 1.0版本接口：返回舊版VO
  @GetMapping(value = "/{id}", version = "1.0")
  public UserV1 getUserV1(@PathVariable Long id) {
    return userService.getV1User(id);
  }

  // 1.1版本接口：返回新版VO（含擴展字段）
  @GetMapping(value = "/{id}", version = "1.1")
  public UserV2 getUserV2(@PathVariable Long id) {
    return userService.getV2User(id);
  }
}

客戶端調(diào)用示例（curl）

# 調(diào)用1.0版本
curl -H "API-Version: 1.0" http://localhost:8080/api/users/1
# 調(diào)用1.1版本
curl -H "API-Version: 1.1" http://localhost:8080/api/users/1

5.3 高級用法：基線版本匹配

使用1.0+表示匹配1.0及以上所有版本，避免未變更接口的版本注解重復編寫：

// 匹配1.0、1.1、1.2等版本，除非有更具體的版本接口
@GetMapping(value = "/list", version = "1.0+")
public List<UserV1> getUserList() {
  return userService.listV1Users();
}

5.4 服務間調(diào)用：API版本自動注入

使用RestClient調(diào)用其他服務時，可配置版本注入器，自動添加版本頭，無需手動設置：

import org.springframework.web.client.RestClient;
import org.springframework.web.servlet.mvc.method.annotation.ApiVersionInserter;

RestClient client = RestClient.builder()
  .baseUrl("http://localhost:8080")
  // 配置Header式版本注入
  .apiVersionInserter(ApiVersionInserter.useHeader("API-Version"))
  .build();

// 調(diào)用時指定版本，自動添加API-Version:1.1頭
UserV2 user = client.get()
  .uri("/api/users/1")
  .apiVersion("1.1")
  .retrieve()
  .body(UserV2.class);

六、替換所有棄用的API

Spring Boot 4.0移除了大量棄用的類和注解，需在IDE中檢查刪除線標注的棄用代碼，替換為官方推薦的替代方案，核心替換點如下：

6.1 空注解替換

// 舊：Spring原生注解
import org.springframework.lang.Nullable;
// 新：JSpecify注解
import org.jspecify.annotations.Nullable;

6.2 Mock相關注解替換

// 舊
import org.springframework.boot.test.mock.mockito.MockBean;
// 新（3.5+推薦）
import org.springframework.test.context.bean.override.mockito.MockitoBean;
// 或直接使用@Mock + MockitoExtension（推薦）

6.3 核心類包遷移

核心消息抽象從spring-context遷移至spring-messaging，若使用相關類，需調(diào)整導入包（IDE會自動提示）。

七、遷移過程中的常見問題與解決方案

結合生產(chǎn)服務的遷移實踐，梳理6類最常見的問題及快速解決方案，覆蓋依賴、測試、配置等核心場景。

問題1：TestRestTemplate 無法解析

錯誤：Cannot resolve symbol 'TestRestTemplate'

解決方案：添加spring-boot-starter-test依賴（測試環(huán)境）或手動添加web自動配置模塊：

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

問題2：MongoTemplate/RedisTemplate 注入失敗

錯誤：No qualifying bean of type 'org.springframework.data.mongodb.core.MongoTemplate'

解決方案：模塊化后，需添加對應的數(shù)據(jù)庫starter，而非僅依賴核心包：

<!-- MongoDB -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>
<!-- Redis -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

問題3：@Mock 字段為null，測試報NPE

錯誤：NullPointerException（Mock對象未初始化）
解決方案：測試類添加@ExtendWith(MockitoExtension.class)，移除棄用的@RunWith(MockitoJUnitRunner.class)。

問題4：JSpecify 注解無提示，IDEA不識別

解決方案：

1. 升級IDEA至2025.3及以上版本；
2. 項目SDK設置為Java 21；
3. 確保添加了JSpecify 1.0.0依賴；
4. IDEA中開啟File > Settings > Build, Execution, Deployment > Compiler > Java Compiler的注解處理。

問題5：路徑式版本控制返回404

錯誤：配置路徑式版本控制后，所有請求返回404
解決方案：@RequestMapping中必須包含{version}路徑變量，Spring通過該變量提取版本：

// 正確
@RequestMapping("/api/{version}/users")
// 錯誤
@RequestMapping("/api/users")

問題6：Maven依賴沖突，Spring Framework版本低于7.0

錯誤：Dependency convergence error（依賴樹中存在Spring Framework <7.0的版本）
解決方案：查看依賴樹，找到引入低版本Spring的依賴并升級/排除：

# 查看Maven依賴樹
./mvnw dependency:tree
# 排除低版本依賴示例
<dependency>
  <groupId>com.example</groupId>
  <artifactId>old-dependency</artifactId>
  <exclusions>
    <exclusion>
      <groupId>org.springframework</groupId>
      <artifactId>spring-context</artifactId>
    </exclusion>
  </exclusions>
</dependency>

八、Spring Boot 3.5 vs 4.0 核心指標對比

基于實際生產(chǎn)服務的遷移實測，核心指標對比如下，直觀體現(xiàn)升級的價值：

九、后續(xù)規(guī)劃與生態(tài)展望

9.1 版本支持與后續(xù)升級

• Spring Boot 3.5.x：官方支持至2026年11月，可根據(jù)業(yè)務節(jié)奏擇機遷移；
• Spring Boot 4.0.1：2025年12月9日發(fā)布，僅修復小BUG，無破壞性變更，可直接升級；
• Spring Boot 4.1：預計2026年Q2發(fā)布，重點增強響應式能力、進一步模塊化，同時優(yōu)化GraalVM原生鏡像構建，降低無服務應用的冷啟動時間。

9.2 生態(tài)兼容注意事項

目前部分第三方庫尚未完成Spring Framework 7.0的適配，遷移前需檢查核心依賴的兼容性：

1. 優(yōu)先使用Spring官方生態(tài)的依賴，兼容性最高；
2. 自定義starter/內(nèi)部庫需提前完成4.0適配；
3. 日志、監(jiān)控等通用庫，優(yōu)先升級至最新版本。

9.3 遷移后的最佳實踐

1. 全面推行空安全編碼：基于JSpecify規(guī)范，所有新代碼添加空注解，逐步改造舊代碼；
2. 基于原生API版本控制：統(tǒng)一團隊的API版本規(guī)范，避免自定義方案的碎片化；
3. 精簡依賴：移除無用的starter，利用模塊化優(yōu)勢進一步降低鏡像體積；
4. 開啟構建期空安全強制校驗：在CI/CD流水線中集成NullAway，拒絕空安全違規(guī)代碼合并。

十、總結

Spring Boot 4.0是一次高性能、高安全性、高開發(fā)效率的重大升級，模塊化的自動配置、原生的空安全校驗、內(nèi)置的API版本控制三大核心特性，不僅帶來了顯著的性能提升，更從框架層面規(guī)范了開發(fā)流程，提前規(guī)避生產(chǎn)環(huán)境的常見BUG。

本次遷移的核心原則是分步升級、前置修復：先升級至3.5.x最新版，修復棄用警告，再檢查并升級基礎環(huán)境，最后正式升級至4.0并修復依賴、編譯問題。從實際實踐來看，無復雜自定義配置的服務，90分鐘內(nèi)可完成遷移；存在自定義自動配置/多依賴的服務，約4小時可完成，整體遷移成本可控。

對于擁有公共API的服務，原生API版本控制特性足以成為遷移的核心理由；對于追求性能的容器/無服務部署場景，19%的鏡像體積減少+33%的啟動時間縮短能直接降低運行成本；而空安全校驗則是長期的價值，能持續(xù)減少生產(chǎn)環(huán)境的空指針故障。

到此這篇關于Spring Boot從3.x到4.0的分步升級保姆級實戰(zhàn)指南的文章就介紹到這了,更多相關Spring Boot3.x升級4.0內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論