JDK17与SpringBoot3.x升级实战指南

1. 升级背景与必要性

最近接手了一个从JDK8+SpringBoot2.x升级到JDK17+SpringBoot3.x的项目，整个过程踩了不少坑，也积累了一些经验。Java生态这几年变化很大，JDK17是LTS版本，SpringBoot3.x也带来了很多新特性，这次升级不仅能获得性能提升，还能使用新语法特性。不过升级过程中确实遇到了不少兼容性问题，特别是包路径变更和依赖冲突。

注意：建议在开发环境先完整测试后再上生产，某些改动会影响线上稳定性。

2. 环境准备与基础配置

2.1 JDK版本升级

首先修改pom.xml中的Java版本配置：

xml复制<properties>
    <java.version>17</java.version>
    <!-- 明确指定编译版本 -->
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

这个改动本身不会引起问题，但需要注意：

1. 本地开发环境需要安装JDK17
2. CI/CD流水线需要同步更新JDK版本
3. 确保Maven使用的是兼容JDK17的版本（建议3.8+）

2.2 Spring Boot父POM升级

将父POM升级到Spring Boot 3.5.0：

xml复制<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.0</version>
</parent>

同时需要更新相关依赖版本：

xml复制<properties>
    <swagger.version>2.2.0</swagger.version> <!-- 改用SpringDoc -->
    <fastjson.version>2.0.51</fastjson.version>
    <mapstruct.version>1.5.5.Final</mapstruct.version>
    <mybatis-plus.version>3.5.6</mybatis-plus.version>
</properties>

3. 关键依赖变更与适配

3.1 Swagger到SpringDoc的迁移

Spring Boot 3不再支持Springfox Swagger，需要迁移到SpringDoc：

xml复制<!-- 替换Swagger为SpringDoc（OpenAPI 3） -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

注解对应关系：

3.2 数据库相关依赖

MySQL驱动坐标和版本变化：

xml复制<!-- 新版MySQL驱动 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.3.0</version>
    <scope>runtime</scope>
</dependency>

<!-- Druid适配Spring Boot 3的starter -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid-spring-boot-3-starter</artifactId>
    <version>${druid.version}</version>
</dependency>

3.3 POI依赖结构调整

POI 5.x后结构变化较大：

xml复制<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.5</version>
</dependency>
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.5</version>
</dependency>

变化点：

1. poi-ooxml现在内置精简版schema
2. 如需完整版schema，需单独引入poi-ooxml-full

3.4 其他核心依赖

xml复制<!-- MyBatis-Plus适配Spring Boot 3 -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>${mybatis-plus.version}</version>
</dependency>

<!-- Knife4j适配版 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

4. 代码层面的适配改造

4.1 javax到jakarta包迁移

最大的变化是javax.包全部迁移到jakarta.：

java复制// 旧导入
import javax.servlet.http.HttpServletRequest;
import javax.persistence.Entity;

// 新导入
import jakarta.servlet.http.HttpServletRequest;
import jakarta.persistence.Entity;

IDE可以批量替换，但需要注意：

1. 某些注解可能有行为变化
2. JPA实体需要重新验证
3. 安全配置需要调整

4.2 集合类使用JDK原生实现

Spring Boot 3推荐使用JDK原生集合类替代Guava：

java复制// 旧代码
ImmutableList.of("a", "b");
Sets.newHashSet(list);

// 新代码
List.of("a", "b");
new HashSet<>(list);

4.3 RedisTemplate泛型调整

RedisTemplate的泛型检查更严格：

java复制// 旧配置
RedisTemplate<Object, Object> redisTemplate;

// 新配置
RedisTemplate<String, Object> redisTemplate;

对应的操作方法也需要调整：

java复制// 旧代码
redisTemplate.delete(keys); // keys是Set类型

// 新代码
redisTemplate.delete(new ArrayList<>(keys)); // 转为List

4.4 Spring Security配置更新

WebSecurityConfigurerAdapter已被移除，改为组件式配置：

java复制@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/api/public/**").permitAll()
            .anyRequest().authenticated()
        )
        .formLogin(form -> form
            .loginPage("/login")
            .permitAll()
        );
    return http.build();
}

路径匹配规则也有变化：

java复制// 旧模式
antMatchers("/**/*.js")

// 新模式
requestMatchers("/**.js")

5. 常见问题与解决方案

5.1 SLF4J日志冲突

报错：No SLF4J providers were found

解决方案：

1. 移除自定义的logback版本配置
2. 确保没有commons-logging残留
3. 使用Spring Boot管理的日志版本

5.2 MyBatis-Plus兼容性问题

报错：Invalid value type for attribute 'factoryBeanObjectType'

解决方法：

1. 使用正确的starter坐标：mybatis-plus-spring-boot3-starter
2. 版本至少3.5.5+

5.3 Hibernate Dialect变更

MySQL5InnoDBDialect已移除，现在会根据URL自动选择方言。

配置示例：

yaml复制spring:
  jpa:
    hibernate:
      ddl-auto: none
      show-sql: true

5.4 FastJSON 2.x的AutoType问题

FastJSON 2.x需要显式开启AutoType：

java复制// 序列化
JSON.toJSONString(obj, JSONWriter.Feature.WriteClassName);

// 反序列化
JSON.parseObject(json, clazz, JSONReader.Feature.SupportAutoType);

5.5 Jackson行为变化

1. @JsonProperty不再fallback到字段名
2. 日期默认序列化为时间戳
3. 对未知属性更严格

解决方案：

java复制@Bean
public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() {
    return builder -> {
        builder.featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        builder.featuresToEnable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
    };
}

5.6 Redis缓存动态创建

Spring Boot 3中RedisCacheManager默认不允许动态创建缓存：

java复制@Bean
public CacheManager cacheManager(RedisConnectionFactory factory) {
    return RedisCacheManager.builder(factory)
            .cacheDefaults(RedisCacheConfiguration.defaultCacheConfig())
            .transactionAware()
            .build();
}

6. 升级检查清单

为确保升级成功，建议按以下步骤验证：

1. [ ] JDK版本验证：java -version确认是17
2. [ ] Maven编译：mvn clean compile无报错
3. [ ] 启动测试：应用能正常启动
4. [ ] API测试：核心接口功能正常
5. [ ] 日志检查：无警告和错误日志
6. [ ] 性能测试：确认无性能退化

7. 经验总结

1. 依赖管理：建议先用mvn dependency:tree分析依赖冲突
2. 渐进式升级：可以先升级到JDK11+Spring Boot 2.7，再升级到目标版本
3. 测试覆盖：确保有足够的单元测试和集成测试
4. 回滚方案：准备好快速回滚的方案

升级过程中最耗时的部分是处理各种依赖冲突和行为变化。建议建立一个checklist记录所有修改点，方便后续验证和回滚。Spring Boot 3.x整体上更规范，但一些"宽松"的处理方式被收紧后，会暴露出原有代码中的潜在问题。