The migration to Spring Boot 3 boasting numerous enhancements, including baked-in support for GraalVM Native Image, is in full swing! If you are just embarking on this journey, below is a guide how to painlessly upgrade the version of your favorite framework.
Please note that the gradual migration is recommended, so make sure you switch to Spring Boot 2.7 before proceeding.
Table of Contents
Upgrade to Java 17
Spring Boot 3.0 requires JDK 17 and Spring Framework 6.0, so you have to upgrade your Java version first. If you haven’t done this yet, our instructions on moving the workloads from JDK 8 or JDK 11 to JDK 17 will guide you through the process.
In addition, you need to upgrade many dependencies. Here’s a list of versions compatible with Spring Boot 3.0, but you should also keep track of libraries not managed by Spring Boot directly. You should also verify that third-party libraries you use are compatible with Spring Boot 3.0 and make relevant changes.
Check for deprecated code
According to the Spring Boot Deprecations policy, methods, constructors, or classes marked as @deprecated are removed from the framework in two minor releases, so if you are migrating from Spring Boot 2.7, verify that your code doesn’t utilize deprecated functionality. To find calls to deprecated features easily, you can use a -Werror option that treats all warnings as errors and fails the build.
Core changes
Spring Boot 3.0 introduces several changes to its core functionality.
Configuration properties
Some configuration properties were renamed or removed, for example:
spring.data.cassandra.was moved tospring.cassandra.spring.redis.was moved tospring.data.redis.management.metrics.export.<product>was moved tomanagement.<product>.metrics.exportserver.max-http-header-sizewas deprecated in favor of a newserver.max-http-request-header-size
Therefore, you need to update your application.properties or application.yml file. You can use the spring-boot-properties-migrator dependency, which identifies such properties and temporarily migrate them at runtime.
Jakarta EE
Spring Boot uses Jakarta EE 10, so other technologies were upgraded as well for compatibility sake. For instance, Spring Boot 3.0 uses Servlet 6.0 and JPA 3.1. You need to update your pom.xml file accordingly.
Furthermore, Jakarta EE 10 utilizes jakarta packages instead of javax, so you may have to fix your import statements.
Logging date format
The new default date and time format for the log messages is now yyyy-MM-dd’T’HH:mm:ss.SSSXXX, where T separates the date and time, and XXX stands for the timezone offset. The new format conforms to ISO-8601 standard, but if you want to use the previous format (yyyy-MM-dd HH:mm:ss.SSS), you can do that with the LOG_DATEFORMAT_PATTERN environment variable or logging.pattern.dateformat property.
Auto-configuration files
Spring Boot 3.0 introduces a new META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file, which substitutes the deprecated method of registering auto-configurations in spring.factories.
Web applications changes
Trailing slash matching
The trailing slash matching configuration has been deprecated, and its default property is set to false. It means that in the case of a similar annotation @GetMapping("/home/hello"), the controller will match only on “GET /home/hello”, but "GET /home/hello/” will result in 404 error.
Apache HttpClient
The RestTemplate was upgraded to HttpClient 5. Apache HttpClient version 4 is no longer supported. The valid replacement is org.apache.httpcomponents.client5:httpclient5.
Pattern parsing
Spring MVC now uses PathPatternParser by default. Although it is possible to override this behavior manually, The Spring team recommends using PathPatternParser whenever possible due to its superior performance.
Actuator changes
Some essential updates introduced to the actuator module are as follows.
“httptrace” renamed
The httptrace endpoint was renamed to httpexchanges to avoid confusion with Micrometer Tracing parameters. Consequently, the related classes were also renamed, for instance, HttpTraceRepository turned into HttpExchangeRepository.
Endpoints sanitization
Spring masked the sensitive key values in /env and /configprops endpoints before, but the new framework version implements an even more secure approach. Now, all values are masked by default. You can use one of the following values to define whether the values are shown or not:
NEVER— all values are masked (default);ALWAYS— all values are shown;WHEN_AUTHORIZED— values are shown if the user is authorized. Users are always considered to be authorized for JMX. In the case of HTTP, users are authorized if they are authenticated and have specified roles.
Actuator JSON
An isolated ObjectMapper instance is now used for responses from the actuator endpoints. In case you implement custom endpoints, make sure that responses implement the OperationResponseBody interface to take ObjectMapper into consideration when serializing responses as JSON.
GraalVM Native Image support
One of the most exciting features of Spring Boot 3.0 is the out-of-the-box support for GraalVM Native Image! Developers can now turn their Spring Boot apps into performant native images with an almost instant startup using Maven or Gradle plugins without special configuration, taking advantage of
- Cloud Native buildpacks or
- Native Build tools.
In the latter case, you need to install a native-image compiler. The Spring team recommends Liberica Native Image Kit (NIK) for that purpose, which is also used as the default native-image builder in Paketo buildpacks.
We prepared a guide on working with native images for Spring Boot developers — you will find here a step-by-step instruction to integrating Native Image into your project as well as tips and recommendations on overcoming possible compatibility challenges.
Spring Security changes
Spring Boot 3.0 supports Spring security 6.0. It is recommended to migrate to Spring Security 5.8 first, and then complete the transition to version 6.0. Necessary code adjustments depend on whether you have a Servlet or Reactive application, but some of the most significant changes are described below.
ReactiveUserDetailsService
A ReactiveUserDetailsService is not auto-configured anymore if the AuthenticationManagerResolver is present.
SAML2
The spring.security.saml2.relyingparty.registration.{id}.identity-provider properties are no longer supported, so developers should use new spring.security.saml2.relyingparty.registration.{id}.asserting-party ones.
Data access changes
Hibernate
Spring Boot 3.0 supports Hibernate 6.1 by default, so if you have a separate dependency for Hibernate, you need to update it. The version 6.1 encompasses two major changes related to basic array/collection mappings and enum mapping, but Hibernate 6.0 includes numerous updates that may affect your application, so if you use older Hibernate versions, consult the Hibernate 6.0 Migration Guide first.
Elasticsearch
Elasticsearch’s high-level REST client is no longer supported. Instead, Spring Boot supports auto-configuration of other Elasticsearch clients: low-level REST client, Java API client, and ReactiveElasticsearchClient provided by Spring Data Elasticsearch.
In addition, ReactiveElasticsearchRestClientAutoConfiguration was renamed to ReactiveElasticsearchClientAutoConfiguration and moved to org.springframework.boot.autoconfigure.elasticsearch.
MySQL JDBC Driver
The MySQL JDBC Driver is now referred to as com.mysql:mysql-connector-j instead of mysql:mysql-connector-java.
New Alpaquita Containers to slash RAM consumption
While you are upgrading your Spring Boot, consider breathing new life into your containers as well!
Alpaquita Containers are tailored to increasing the performance of your containerized Spring Boot apps. Based on
- a lightweight Alpaquita Linux with two libc options and four mallocs for various Java workloads and
- Liberica JDK Lite, a Liberica JDK flavor for cloud deployments,
They will help you instantly reduce the RAM consumption of containers by up to 30 %. Test them out and see for yourself!
