导读qkl-boot 脚手架要从 Spring Boot 2.7 升级到 3.5.16 Java 17开工前以为换个版本号就行结果踩了一串坑javax 全部变 jakarta、循环依赖启动直接报错、MyBatis-Plus 要换 starter、Knife4j 也要换 Jakarta 版。这篇是完整升级实录照着避坑。qkl-boot 从 Spring Boot 2.7 升到 3.5javax 没了、循环依赖禁了、MyBatis-Plus 也得换版本先说背景。qkl-boot 原本基于 Spring Boot 2.7 Java 8这次要整体升级到 Spring Boot 3.5.16 Java 17JDK 21 也能跑。升级完跑起来用了整整一天全是版本兼容问题。第一步pom 换依赖三个坑排队等着Spring Boot 3 的依赖坐标变化是第一个大坑。直接看现在的 pom17 3.5.16 org.springframework.boot spring-boot-dependencies ${spring-boot.version} pom import注意 Spring Boot 3 起很多 starter 的包名和坐标都变了com.baomidou mybatis-plus-spring-boot3-starter com.github.xiaoymin knife4j-openapi3-jakarta-spring-boot-starter我一开始没换 MyBatis-Plus starter启动报NoSuchBeanDefinitionException: SqlSessionFactory排查半天才发现是坐标不对。老坐标mybatis-plus-boot-starter在 Boot 3 下不认。第二步javax 全部换 jakarta全局替换别漏Spring Boot 3 把 JavaEE 换成 Jakarta EEjavax.*全部变jakarta.*。代码里的 import 要全局替换// 升级前javaximportjavax.annotation.Resource;importjavax.validation.constraints.NotBlank;importjavax.servlet.http.HttpServletRequest;// 升级后jakartaimportjakarta.annotation.Resource;importjakarta.validation.constraints.NotBlank;importjakarta.servlet.http.HttpServletRequest;注意javax.annotation.Resource换成了jakarta.annotation.Resource这个最容易漏因为 IDE 不报编译错也能跑启动时才报NoSuchBeanDefinitionException排查很费劲。建议全局搜索javax.逐个确认。第三步循环依赖Boot 2.6 默认直接禁止升级后启动报错日志片段The dependencies of some of the beans in the application context form a cycle: ┌─────┐ | jobService ↑ ↓ | resumeService └─────┘Spring Boot 2.6 起默认禁止循环依赖老项目两个 Service 互相注入的写法直接启动失败。排查过程找到互相依赖的两个类jobService注入resumeServiceresumeService又注入jobService。定位思路循环依赖是设计问题别用spring.main.allow-circular-referencestrue强行放开那是把问题埋起来。最终解决拆解依赖方向只保留单向调用ServicepublicclassResumeService{// 只注入 JobServiceJobService 不再注入回来ResourceprivateJobServicejobService;}把互相调用的公共逻辑抽到独立 Service 或者用事件驱动循环引用从根上拆掉。第四步配置类和拦截器包路径全变了WebMvcConfigurerAdapter在 Boot 3 里改名WebMvcConfigurer其实 2.x 就废了但升级时容易踩拦截器注册也变了ConfigurationpublicclassWebConfigimplementsWebMvcConfigurer{OverridepublicvoidaddInterceptors(InterceptorRegistryregistry){registry.addInterceptor(newTokenInterceptor()).addPathPatterns(/api/**).excludePathPatterns(/api/auth/login,/api/auth/register);}}同时spring.factories自动装配机制在 Boot 3 里被AutoConfiguration.imports文件取代自定义 starter 的配置类要挪位置# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports com.qkl.boot.autoconfigure.QklAutoConfiguration这个文件放错位置自定义 starter 静默失效没有任何报错接口全都 404排查起来非常阴间。踩坑Redis 客户端从 Jedis 变 Lettuce连接池配置失效现象升级后 Redis 连接一直报Unable to connect to Redis配置里明明写了连接池。排查过程Boot 3 默认用 Lettuce我把spring.redis.jedis.pool.*的配置留着Jedis 相关的配置项全部失效。定位思路看 Boot 3 文档spring.data.redis.lettuce.pool.*才是 Lettuce 的配置前缀。最终解决spring:data:redis:host:127.0.0.1port:6379lettuce:pool:max-active:16max-idle:8min-idle:2Spring Boot 3 的配置前缀从spring.redis变成了spring.data.redis这个改动也容易漏配置不生效但不报错。可直接复用的要点Spring Boot 3 的javax→jakarta 全局替换javax.annotation.Resource最容易漏启动才报错。MyBatis-Plus 必须用mybatis-plus-spring-boot3-starterKnife4j 用knife4j-openapi3-jakarta-spring-boot-starter。循环依赖 Boot 2.6 默认禁止拆解依赖方向别开allow-circular-references。spring.factories换成AutoConfiguration.imports放错位置自定义 starter 静默失效。Redis 配置前缀变成spring.data.redis客户端默认 Lettuce。升级后挨个模块启动验证别一次性跳大版本2.7→3.0→3.5 分步走更稳。项目源码https://gitee.com/gzqkl/qkl-boot