Spring Boot 3.0升级指南

Spring Boot 3.0 现已正式发布，它包含了12个月以来151个开发者的5700多次代码提交。这是自4.5年前发布 2.0 以来，Spring Boot 的第一次重大修订。

它也是第一个支持 Spring Framework 6.0 和 GraalVM 的 Spring Boot GA 版本，同时也是第一个基于Java 17的Spring Boot版本，以Jakarta EE 9为基准并支持Jakarta EE 10。同时借助于GraalVM支持了AOT和Native Image。

一、3.0升级指南

如果你想尝试Spring Boot 3.0，不妨参考这份升级指南。

1、升级JDK

首先要升级你的JDK到JDK17，如果你要使用Native Image特性，要使用GraalVM 22.3以上和 Native Build Tools Plugin 0.9.17 或更高的版本。

2、平滑升级

这里不建议直接从低于Spring Boot 2.7的版本直接升级到Spring Boot 3.0。不然新特性和API变更太多，就需要你修改大量的配置，升级路径会过于陡峭。建议通过小版本号分阶段升级到2.4、2.6、2.7，最后再到3.0。

3、依赖评估

Spring Boot3.0下依赖组件的版本要求也不尽相同，比如Spring Boot Kafka Starter可能对Kafka有什么要求，这要求你进行充分评估。Spring Cloud体系应该在对应的Spring Boot 3.0体系发布后进行升级。

4、升级到Spring Boot 3

一旦上面的工作准备完毕，你就可以开始尝试升级到Spring Boot 3.0了。

二、配置属性兼容

在Spring Boot 3.0中，一些配置属性被重新命名/删除了，开发人员需要相应地更新他们的application.properties或者application.yml。为了帮助你做到这一点，Spring Boot 3.0提供了一个spring-boot-properties-migrator模块。一旦作为依赖关系添加到你的项目中，它不仅会在启动时分析你的应用程序的环境并打印诊断结果，而且还会在运行时为你临时迁移属性。把下面这个加入pom.xml以帮助你升级兼容配置属性：

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

完成迁移之后，务必要移除spring-boot-properties-migrator依赖。

三、 Jakarta EE

由于Java EE已经变更为Jakarta EE，包名以 javax开头的需要相应地变更为jakarta。这里建议通过Intellij IDEA 2021.2提供的内置功能批量处理即可。

当然你也可以手动去变更包名。

四、升级的关键变更

Spring Boot 3.0有一些关键改变，这些改变将与大多数应用程序有关。所以开发者要仔细阅读这些变更。

1、图片Banner不再支持

现在Spring Boot 3.0自定义Banner只支持文本类型（banner.txt），不再支持图片类型。

2、日志日期格式变更

Logback和Log4j2的日志消息的日期和时间部分的默认格式已经改变，以符合ISO-8601标准。新的默认格式yyyy-MM-dd'T'HH:mm:ss.SSSXXX使用T来分隔日期和时间，而不是空格字符，并在最后添加时区偏移。LOG_DATEFORMAT_PATTERN环境变量或logging.pattern.dateformat属性可以用来恢复以前的默认值yyyy-MM-dd HH:mm:ss.SSS。

3、ConstructingBinding注解

配置属性类注解@ConfigurationProperties默认情况下不再需要使用@ConstructorBinding来标记构造，你应该从配置类上移除它，除非该配置类多个构造函数来明确配置属性绑定。

4、YamlJsonParser被移除

因为SnakeYAML的JSON解析与其他解析器的实现不一致。如果你直接使用YamlJsonParser，请迁移到其他JsonParser实现中。

5、自动配置文件变更

Spring Boot 2.7引入了一个新的文件：

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

用于注册自动配置，同时保持与 spring.factories 中注册的向后兼容。Spring Boot 3.0发布后，spring.factories已经被移除，只能通过imports文件来注册自动配置。

6、Web应用变更

1）路径匹配

现在Spring MVC和Spring Webflux 的路径匹配规则已经做了调整，默认情况下尾部斜杠/的匹配机制将和以前不同：

• 3.0以前/foo/bar等同于/foo/bar/
• 3.0以后/foo/bar不同于/foo/bar/

2）弃用配置 server.max-http-header-size

server.max-http-header-size已经被弃用，现在用server.max-http-request-header-size替代 ，并且现在该属性只能来配置请求头的大小，不再限制某些Web容器的响应头大小，如果需要限制响应头大小请通过自定义WebServerFactoryCustomizer来实现。

3）优雅停机阶段变更

优雅停机由SmartLifecycle实现，在SmartLifecycle.DEFAULT_PHASE - 2048阶段开始，Web服务器在SmartLifecycle.DEFAULT_PHASE - 1024阶段停止。任何参与优雅关机的SmartLifecycle实现都应该被相应地更新。

4）Jetty

由于Jetty目前还不支持Servlet 6.0，使用Jetty的开发者需要通过降低Jakarta Servlet的版本为5.0。

7、数据访问相关的变更

spring.data前缀已被保留给Spring Data项目，如果你使用了Spring Data项目的子项目，application.yaml中相关的配置属性就需要响应的变更。例如 spring.redis现在需要修改为spring.data.redis。

1）数据访问相关的组件

数据访问相关的组件现在都使用了比较新的版本：

• Flyway更新到 9.0
• Hibernate 更新到 6.1
• R2DBC 更新到 1.0

2）Mongodb

另外 Flapdoodle 嵌入式 MongoDB 的自动配置被移除，开发者有需要的话需要自行引入。

3）Elasticsearch

Elasticsearch的Rest客户端采用了新的API实现，旧的自动配置和Spring Data Elasticsearch中旧的客户端API已经被移除。

8、其它变更

Spring Security、可观测性、度量跟踪、Maven、Gradle也都有不同程度的变更，有需要可以查看官方的Spring-Boot-3.0-Migration-Guide 。