升级 Spring Boot

关于如何从旧版本的 Spring Boot 升级的说明，请参考项目 Wiki。你可以点击 发布说明 (Release Notes) 链接找到你要升级到的目标版本。

升级说明通常位于每份发布说明的第一项。如果你落后了多个版本，请务必也查看你跳过的那些版本的发布说明。

1. 从 1.x 升级

如果你正从 Spring Boot 1.x 升级，请参考 Wiki 上的 迁移指南，该指南提供了升级到 2.x 的详细说明。

2. 从 2.x 升级

如果你从 Spring Boot 2.x 升级，请查看 Wiki 上的 Spring Boot 3.0 迁移指南。由于跨度较大，请关注 Spring 框架版本更新带来的重大变化。

3. 从 3.x 升级

如果你从 Spring Boot 3.x 升级，请查阅 Spring Boot 4.0 迁移指南。这是目前最新的主版本升级路径。

4. 属性迁移助手 (Properties Migrator)

在升级到新的特性版本时，某些配置属性可能已被重命名或移除。Spring Boot 提供了一个模块，可以在启动时分析你的应用环境并打印诊断信息，同时在运行时为你临时迁移属性。

要启用此功能，请在项目中添加以下依赖：

Maven

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-properties-migrator</artifactId>
	<scope>runtime</scope>
</dependency>

Gradle

runtimeOnly 'org.springframework.boot:spring-boot-properties-migrator'

警告

通过较晚阶段添加到环境中的属性（例如使用 @PropertySource 加载的属性）将不会被处理。

提示

一旦你根据打印的日志信息完成了所有配置属性的修改，请确保将该模块从项目依赖中移除。

---

补充教学

1. 为什么“版本跳跃”需要格外小心？

比如你从 2.1 直接跳到 3.0，你会错过 2.2 到 2.7 之间版本逐渐废弃（Deprecated）的功能。直接跨大版本可能会遇到“断崖式”的错误。因此，逐个小版本升级并解决其间的编译警告，是大型系统最稳健的策略。

2. Spring Boot 3.0+ 的重大分水岭：Jakarta EE

这是升级中最大的坑。从 3.x 开始，Spring 将底层从 javax.* 包名全面切换到了 jakarta.*。这意味着你的所有 Servlet 解析器、JPA 注解、甚至某些第三方库都需要同步升级包名。

3. 如何判断升级是否成功？

除了能跑通所有测试用例（Test Cases）外，还应重点关注 Actuator 的 /health 端点和 /metrics。有些老版本的监控指标在 3.x 之后发生了变化，可能会导致你原有的 Prometheus 报警失效。

4. CLI 的升级

现有的 CLI 安装可以通过包管理器命令更新（如 brew upgrade）。如果是手动安装的，建议直接下载新包覆盖，并确保系统的 PATH 变量指向了正确的 bin 目录。