Spring Boot 2.x → 3.x 全链路迁移记录：javax→jakarta 与 Security 6 的 10 个坑
Spring Boot 2.x → 3.x 全链路迁移记录javax→jakarta 与 Security 6 的 10 个坑原创声明本文基于本人课程实训期间独立开发的 CoolShark 微服务电商平台Spring Cloud Alibaba实战经验整理为第一手踩坑记录内容已脱敏。项目代码已开源https://github.com/yunxuan4309/csmall实战复盘 · 框架大版本升级项目背景微服务电商平台8 个业务模块从 Spring Boot 2.x 升级到 3.x涉及 Jakarta EE 9、Spring Security 6.x、MyBatis-Plus 新版本。本文记录了全链路迁移的踩坑清单。一、坑 1Servlet API 包名变更javax → jakarta现象编译报错Cannot resolve symbol ServletException、Cannot resolve symbol HttpServletRequest。根因Spring Boot 3.x 基于 Jakarta EE 9所有javax.*包名重命名为jakarta.*。解决// 修复前importjavax.servlet.FilterChain;importjavax.servlet.ServletException;importjavax.servlet.http.HttpServletRequest;importjavax.servlet.http.HttpServletResponse;// 修复后importjakarta.servlet.FilterChain;importjakarta.servlet.ServletException;importjakarta.servlet.http.HttpServletRequest;importjakarta.servlet.http.HttpServletResponse;涉及面8 个模块的 SSOFilter、MyAccessDeniedHandler、MyAuthenticationEntryPoint、ResourceWebSecurityConfiguration 等 25 文件。二、坑 2WebSecurityConfigurerAdapter 已移除Spring Security 6.x 移除了WebSecurityConfigurerAdapter改为SecurityFilterChain Bean Lambda DSL// 旧5.xhttp.csrf().disable();http.authorizeRequests().antMatchers(/public/**).permitAll();// 新6.xhttp.csrf(csrf-csrf.disable());http.authorizeHttpRequests(auth-auth.requestMatchers(/public/**).permitAll());其他关键变更EnableGlobalMethodSecurity→EnableMethodSecuritysetAllowedOrigins(*)→setAllowedOriginPatterns(*)http.sessionManagement().sessionCreationPolicy(...)→http.sessionManagement(session - session.sessionCreationPolicy(...))三、坑 3Gateway Knife4j 循环依赖Knife4jSwaggerProvider使用Autowired直接注入RouteLocator形成循环依赖。解决使用ObjectProviderRouteLocator构造器注入 getIfAvailable()延迟加载。四、坑 4MyBatis-Plus Starter 不兼容必须用mybatis-plus-spring-boot3-starter不能用mybatis-plus-boot-starter分页插件3.5.9 将分页插件移到独立模块需额外添加mybatis-plus-jsqlparser依赖分页类型转换IPageModel无法直接转IPageVO需手动 stream convertToVO newPageAPI 变更mapper.update(entity)→mapper.updateById(entity)selectCount()返回long不是int代码生成器AutoGenerator→FastAutoGenerator五、坑 5实体类与数据库字段映射TableName 缺失MyBatis-Plus 默认用类名转蛇形作为表名如Spu→spu但实际表名是pms_spu。为 25 个实体类添加TableName注解。is_ 前缀字段不匹配MyBatis-Plus 将deleted映射为列deleted但数据库实际列名是is_deleted。为 5 个字段添加TableField注解。pms_category 表结构不一致Mapper XML 期望的字段depth、keywords、enable与数据库实际字段level、is_parent、is_display不匹配。六、坑 6SPU 测试数据不可见init-test-data.sql中 SPU INSERT 未显式设置is_checked和is_deleted默认 0 导致前端查询不到商品。解决显式设置is_checked1, is_deleted0。七、其他小坑汇总问题解决org.apache.commons.lang.StringUtils找不到改为org.apache.commons.lang3.StringUtilsNacosRandomUtils不可用改为ThreadLocalRandomMediaType.APPLICATION_JSON_UTF8废弃直接用APPLICATION_JSONRFC 8259CORSsetAllowedOrigins(*)报错setAllowedOriginPatterns(*)setAllowCredentials(true)Long 精度丢失雪花 ID 19 位全局 Jackson 配置 Long → String 序列化八、经验总结大版本升级先列受影响面清单javax→jakarta、Security 6 的 API 变更波及 8 个模块 25 文件提前梳理避免遗漏编译错误只是第一关JJWT 密钥长度、CORS 配置这类问题编译期不报运行时才暴露升级后必须全功能回归框架升级往往伴随第三方库连锁升级MyBatis-Plus、JJWT、Nacos 客户端都要同步适配写清楚旧→新对照表本文所有变更都以对照表形式记录方便全局搜索替换和他人参考
