Upgrading a Campus Blog Project to JDK 17 and Spring Boot 3: Process, Pitfalls, and Solutions

Why Upgrade?

The author decided to upgrade the project because JDK 17 is an LTS version, offers new language features (var, records, text blocks, enhanced switch and instanceof), supports native images, and aligns with industry trends and company requirements.

Benefits of the Upgrade

JDK 17 brings performance improvements with ZGC, local‑variable type inference, multiple public classes per file, simplified switch statements, enhanced instanceof, records, and text blocks.

Spring Boot 3 adds native‑image support via GraalVM, upgrades to Spring 6 and Spring Security 6, among other new features.

Upgrade Process

Upgrade to JDK 17

Install JDK 17 directly in IntelliJ IDEA and update the project and module SDKs.

<properties>
  <java.version>17</java.version>
  <maven.compiler.source>${java.version}</maven.compiler.source>
  <maven.compiler.target>${java.version}</maven.compiler.target>
</properties>

Re‑package the project with Maven, then start all micro‑services to verify that everything runs correctly.

Update Dockerfile

Replace the base image java:8-alpine with amazoncorretto:17-alpine and adjust JVM options.

# Set JAVA version
FROM amazoncorretto:17-alpine
VOLUME /tmp
ARG JAR_FILE
ADD ${JAR_FILE} app.jar
ENV JAVA_OPTS "\
-server \
-Xms256m \
-Xmx512m \
-XX:MetaspaceSize=256m \
-XX:MaxMetaspaceSize=512m \
-Duser.timezone=GMT+08 "
ENV PARAMS ""
ENTRYPOINT ["sh","-c","java -jar $JAVA_OPTS /app.jar $PARAMS"]

Upgrade to Spring Boot 3.2

Update the pom.xml dependencies: Spring Boot from 2.6.11 to 3.2.1, Spring Cloud to 2023.0.0, MyBatis‑Plus starter to mybatis-plus-spring-boot3-starter , Druid starter to druid-spring-boot-3-starter , and optionally upgrade Maven.

Dependency

Before

After

Notes

SpringBoot

2.6.11

3.2.1

Latest GA version

SpringCloud

2021.0.4

2023.0.0

Matches Spring Boot 3.2

Mybatis‑Plus

3.5.3.1

3.5.5

ArtifactId changed

druid

1.2.11

1.2.20

ArtifactId changed

Resolve Dependency Issues

Replace the old MySQL connector coordinate mysql:mysql-connector-java with com.mysql:mysql-connector-j and change all javax.servlet imports to jakarta.servlet (including Maven coordinates).

Configuration Property Migration

Spring Boot 3 renamed several properties, e.g., spring.redis.host → spring.data.redis.host . Adding the spring-boot-properties-migrator dependency helps detect and migrate these keys.

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

Elasticsearch Compatibility

The project uses spring-boot-starter-data-elasticsearch which, after the upgrade, expects Elasticsearch 8.x while the server runs 7.x. The author adds a custom RestClientBuilderCustomizer to inject the required X-Elastic-Product header and disable the incompatible compatible-with request header.

@Component
public class EsCompatibilityConfig implements RestClientBuilderCustomizer {
    @Override
    public void customize(RestClientBuilder builder) {}
    @Override
    public void customize(HttpAsyncClientBuilder builder) {
        HttpResponseInterceptor interceptor = (response, context) ->
            response.addHeader("X-Elastic-Product", "Elasticsearch");
        builder.addInterceptorLast(interceptor);
        builder.setDefaultHeaders(List.of(new BasicHeader(HttpHeaders.CONTENT_TYPE,
            ContentType.APPLICATION_JSON.toString())));
    }
}

Spring Cloud WARN Issue

After upgrading, a large number of WARN messages appear about beans not being eligible for all BeanPostProcessors. The issue is traced to a Spring Cloud bug (issue #1315) and fixed by upgrading spring-cloud-commons to version 4.1.1.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-commons</artifactId>
      <version>4.1.1</version>
      <scope>compile</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Auto‑Configuration Migration

Spring Boot 2.7 introduced the META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file to replace spring.factories . The author recommends migrating to the new mechanism to avoid future compatibility problems.

Conclusion

The migration took about two weeks and involved many pitfalls, especially when upgrading Spring Boot. The author provides links to official migration guides, release notes, and the GitHub pull requests containing the changes. Readers are encouraged to review the official documentation for any additional impact before upgrading.

Postscript

The author asks readers to like, watch, share, and bookmark the article, and invites them to follow the public account “码猿技术专栏” for more technical content and community discussions.