如果你正在接手或维护一套 datax-web社区里通常写成 datax-web也有叫 datax web 的并且最近被要求把它从 Spring Boot 2.x 升到 Spring Boot 3、JDK 8 升到 JDK 17那你大概率已经感受到了那种“说大不大、说小不小”的升级焦虑。我这次升级的是团队内部基于 datax-web 二次开发的调度和同步平台老代码一路从 Spring Boot 2.1 走到 2.3JDK 8 用了很多年直到新部署的机器镜像默认只给 JDK 17、部分配套组件也要求新版兼容才终于下定决心做一次整体迁移。datax-web 的本质是给阿里 DataX 套了一层 Web 管控面解决的是任务可视化配置、手动/定时触发、执行日志查看、权限管理这些事底层真正跑数据同步的还是 DataX 的 Python 脚本。所以升级过程中最难啃的不是 DataX而是外面这层 Spring Boot 应用。这篇文章按照我实际改造的顺序来写老项目盘点、版本路线确定、javax/jakarta 迁移、依赖矩阵、代码实操、构建排错、回归验证最后是一份可以直接抄的常见问题清单。适合正在做老 Spring Boot 项目升级的人参考也适合对 Spring Boot 3 和 Spring Security 6 迁移还没概念的同学当案例看。1. 升级前的技术摸底先别急着改 pom.xml1.1 先搞清楚你手里的是哪个 datax-web 分支datax-web 这个项目社区里有好几个流传版本比较常见的是 WeiYe-Jing/datax-web 这个仓库以及后来各种公司 fork 出来继续魔改的增强分支。这些版本的模块划分大体一致一个 web 控制台负责用户和任务管理一个 executor 执行器负责拉取任务并调用 datax.py前端一般是 Vue Element UI 构建的静态页面。但具体到你手里的代码内部包名、自定义功能、部署方式可能千差万别。我这次拿到的是一套基于 2.x 老分支的二次开发版本登录模块自己改了 JWT 逻辑任务调度基于 Quartz部署方式是打 jar 包然后用 supervisor 托管完全没有用官方推荐的 Docker 方式。如果你手里的也是这种“祖传代码”我建议升级前先花半天把模块边界理清楚至少要知道自定义代码集中在哪个模块、前端产物是打进 Spring Boot 的 static 目录还是单独用 Nginx 托管、有没有外部系统通过 API 在调用 datax-web 的接口。这些因素会直接影响你的升级范围。1.2 升级前必须列清楚的检查清单老项目升级最怕的是“打开 IDE 到处报错”根本原因是依赖太多、版本太乱。我建议先做一次全量盘点把下面这张表填完再动手目标运行环境JDK 版本、操作系统位数、是否有特殊安全基线比如必须用非 root 运行。数据库连接池与驱动用的是什么连接池MySQL 驱动是 com.mysql:mysql-connector-java 还是新坐标。安全认证方式Spring Security、Shiro、JWT 过滤器还是数据库表硬编码账号。任务调度框架Quartz、xxl-job还是自己写的 Timer 线程池。API 文档组件是否用了 springfox SwaggerBoot 3 下 springfox 基本不可用。前端产物登录页、任务配置页是否依赖老接口返回结构。反射和序列化代码里有没有 Fastjson、Gson 对泛型 TypeReference 的使用。外部中间件Redis、ES、MQ哪些是强依赖哪些启动时连不上也不用挂。这些内容看着琐碎但决定你之后是“半天搞定”还是“调一周”。我自己就是没提前登记 WebSocket 的使用场景结果升级到 Spring Boot 3 之后被 javax.websocket 的依赖冲突卡了两个小时。2. JDK 17 和 Spring Boot 3版本路线一次性定清楚2.1 为什么是 JDK 17 而不是继续留在 JDK 8Spring Boot 3 的底层是 Spring Framework 6而 Spring Framework 6 从设计上就把 Java 17 作为基线版本这意味着你想用 Boot 3就必须先把 JDK 升到 17 或更高。JDK 17 又是 LTS 长期支持版本新环境默认装的就是它老应用直接跑在 JDK 17 上老框架的反射、字节码代理很容易触发模块化封装问题所以与其在 JDK 17 上继续跑老 Boot 2.3 去补各种 add-opens不如直接连框架一起升级。如果你在 Windows 或者 Linux 上装 JDK 17步骤并不复杂下载对应的 .tar.gz 或安装包配置 JAVA_HOME 和 PATH然后在启动脚本里显式写死 /path/to/jdk17/bin/java。这里特别提醒一点服务器上如果同时存在 JDK 8 和 JDK 17千万不要依赖全局 PATH否则日志里会出现“Unsupported major.minor version 61.0”这种没头没脑的提示。部署脚本里写死绝对路径是最稳妥的。2.2 javax 到 jakarta 的包名大迁移这是 Spring Boot 3 升级最明显、也最费手的一个变化。Java EE 移交到 Eclipse 基金会之后命名空间从 javax 变成了 jakartaSpring Boot 3 内置的 Servlet 容器已经是 Tomcat 10.1 / Jetty 11 / Undertow 2.2对应的是 Jakarta EE 9 API。所以老代码里的 javax.servlet.* 在编译期直接就找不到类了。我实际遇到的主要是这几个包的替换老包新包说明javax.servlet.*jakarta.servlet.*Filter、Servlet、HttpServletRequest 等javax.validation.*jakarta.validation.*参数校验注解javax.annotation.PostConstructjakarta.annotation.PostConstruct生命周期注解javax.websocket.*jakarta.websocket.*WebSocket 端点和会话javax.persistence.*jakarta.persistence.*如果项目用了 JPAjavax.transaction.*jakarta.transaction.*事务相关 API替换方法我用的是全局搜索兼顾人工确认。IDE 自带 Refactor 功能比如 IDEA 的 Java EE Migration 流程能帮你改一部分但代码里如果是字符串拼接、XML 配置、SPI 文件里写了 javax 全类名就得自己排查了。最靠谱的命令是grep -R javax\. src/把所有命中一条条过一遍宁可多花半小时也不要漏掉某个隐藏在常量里的字符串。2.3 依赖版本矩阵照着这张表挑版本升级依赖不是把所有版本号往大了调就行关键是要确定各个库对 Spring Boot 3 / JDK 17 的适配情况。我这次整理出一套验证过能配合使用的版本组合你直接照抄问题不大但要根据自己项目实际微调组件老版本典型值升级后建议值备注Spring Boot2.3.x3.2.x / 3.3.x3.2 以上对 JDK 17 支持成熟JDK817不要用 21 除非你想当小白鼠MyBatis-Plus3.4.x3.5.5推荐用专门适配 boot3 的 startermysql-connectorcom.mysql:mysql-connector-java:8.0.2xcom.mysql:mysql-connector-j:8.0.33注意坐标已经变了springfox-swagger2.9.x / 3.0.0springdoc-openapi 2.xspringfox 老版本在 Boot 3 下基本不可用Lombok1.18.201.18.30老版本不支持 JDK 17 编译Quartz2.3.x2.3.2 可用但要用 spring-boot-starter-quartz 统一管理Fastjson1.2.681.2.83 或 fastjson2老版本在 JDK 17 下反射兼容性差如果你项目里用了 Redis还要注意 spring-boot-starter-data-redis 在 Boot 3 下依赖的是 Lettuce 6.1老项目的连接池配置项有一些变化启动后要重点看日志里 Redis 连接是否正常输出。3. 核心代码改造实操安全、持久层、WebSocket、启动参数3.1 Spring Security 6WebSecurityConfigurerAdapter 已经彻底没了Spring Security 6 改动最大的地方是 WebSecurityConfigurerAdapter 这个基类被删掉了以前写一坨继承类的配置方式全部要改成 SecurityFilterChain Bean。如果你项目里用的是 Shiro影响没这么大但只要涉及 Spring Security 就要重写。我这次改造的登录模块刚好是 JWT Security 的组合踩的坑基本都集中在这块。新标准写法是定义 SecurityFilterChain Bean我直接贴一段可以用的配置Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http.csrf(csrf - csrf.disable()) .authorizeHttpRequests(auth - auth .requestMatchers(/login, /static/**, /api/auth/**).permitAll() .anyRequest().authenticated() ) .formLogin(form - form.loginPage(/login).permitAll()) .logout(logout - logout.logoutSuccessUrl(/login)) .sessionManagement(session - session .sessionCreationPolicy(SessionCreationPolicy.STATELESS) ); return http.build(); } Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }注意几个关键差异旧版的.antMatchers(/**)变成了.requestMatchers(/**)旧版的.authorizeRequests()变成了.authorizeHttpRequests()旧版的.and()链式调用全部移除。URL 匹配规则也有细节变化旧的/user/*只匹配一级路径新写法推荐用/user/**我实际测试中前者在 Security 6 下的匹配行为有坑。另外过滤器顺序非常重要如果你自定义了 JWT 认证过滤器记得用http.addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)明确指定位置否则会出现“该登录的没登录不该拦的全拦了”的诡异现象。3.2 MyBatis-Plus 和 MyBatis 在 Boot 3 下的兼容处理如果你的老项目用了 MyBatis-Plus 3.4.x直接升级到 Spring Boot 3 后启动时会报 “Failed to introspect Class” 或 “ClassNotFound” 之类的错误本质原因是老版本的 starter 还在走 Spring Boot 2 的自动装配机制。官方从 3.5.3 开始适配 Boot 3我这边用的是 3.5.5实测比较稳。另外一个坑是坐标MyBatis-Plus 官方后来提供了专门给 Spring Boot 3 用的 starter名字叫 mybatis-plus-spring-boot3-starter引入的时候别还是引入原来的 mybatis-plus-boot-starter。还有几个容易忽略的点分页插件、乐观锁插件这些内部 Bean 在 Boot 3 下初始化时机有变化多个数据源时尤其容易因为初始化顺序问题导致 Mapper 扫描不到。如果项目里自己定义过 SqlSessionFactory 或 MybatisSqlSessionFactoryBean建议把所有 Mapper 路径和类型别名重新核对一遍。我这次就遇到过 Mapper XML 文件里写了旧包名的 parameterType编译不报错启动也不报错但运行时任务列表接口直接 500最后排查半天才发现是 XML 里的全限定类名还带 javax。3.3 WebSocket 和 Servlet 容器相关的替换datax-web 这类管控平台经常用 WebSocket 向前端推送执行日志升级过程中这一块也很容易出问题。首先要做的还是把代码里的javax.websocket.*全部替换成jakarta.websocket.*包括ServerEndpoint注解和WebSocketContainer这些。其次要确认依赖坐标Spring Boot 3 工程里建议直接用spring-boot-starter-websocket它会自动带出兼容 Jakarta API 的 Tomcat 包。如果你用的是独立 Tomcat 部署 war 包而不是可执行 jar升级后还要特别注意 servlet-api 冲突。我遇到过“本地启动一切正常放到 Tomcat 上就报 WebSocket endpoint 无法注册”的情况最后是删掉了打包产物里混入的旧 javax.websocket-api 才解决。顺序上建议先跑可执行 jar稳定了再考虑 war 部署能少踩一半坑。3.4 JVM 启动参数--add-opens 是绕不开的JDK 17 对内部的强封装比 JDK 8 严格很多Spring 的 CGLIB 代理、MyBatis-Plus 对实体字段的反射、Fastjson 处理泛型反序列化都可能在运行期出现InaccessibleObjectException。我这边最终在启动脚本里加了一组 add-opens 参数覆盖了常见的反射场景贴出来供参考JAVA_OPTS -server -Xms1024m -Xmx2048m -XX:MaxMetaspaceSize512m --add-opensjava.base/java.langALL-UNNAMED --add-opensjava.base/java.lang.invokeALL-UNNAMED --add-opensjava.base/java.lang.reflectALL-UNNAMED --add-opensjava.base/java.ioALL-UNNAMED --add-opensjava.base/java.netALL-UNNAMED --add-opensjava.base/java.utilALL-UNNAMED --add-opensjava.base/java.util.concurrentALL-UNNAMED --add-opensjava.base/java.textALL-UNNAMED --add-opensjava.base/java.timeALL-UNNAMED --add-opensjava.sql/java.sqlALL-UNNAMED java $JAVA_OPTS -jar datax-web-*.jar如果你是 Windows 环境启动脚本里把写法换成set JAVA_OPTS...其他内容一样。这些参数加上去对正常逻辑没有副作用属于“宁可多开也不要启动到一半挂掉”的保险做法。如果你用的是高版本 Spring Boot 或者某些库升级后已经适配了模块化系统可以逐步删掉不用的项但没必要一开始就精简。3.5 自动装配机制和配置文件迁移老项目如果自己写过 Spring Boot 自动配置类升级时要注意 Spring Boot 3 已经不再读取META-INF/spring.factories里配置的自动装配类必须新建META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件把自动配置类的全限定名写进去。这个改动非常隐蔽因为如果只是普通 Configuration 注解类启动时仍然生效只有自动装配类的加载方式变了。配置项方面Spring Boot 3 对 ConfigurationProperties 的绑定校验更严格类型不匹配会直接启动失败而不是忽略。我用下来最大的感受是老项目里那些约定俗成的配置前缀如果之前没写规范升级后往往会浮出水面。比如spring.redis.*改成spring.data.redis.*这个变化不知道坑了多少老项目你回头看看自己的 application.yml是不是还在用spring.redis.host4. 构建、启动与 DataX 任务回归4.1 先让编译干净跑通升级代码改完之后第一件要做的事不是启动服务而是把整个工程在 JDK 17 下编译通过。我用的是 Maven命令很简单mvn clean package -Dmaven.test.skiptrue如果模块很多建议先mvn clean compile快速暴露出所有 javac 编译错误重点是 javax 相关 import。如果编译时报 “程序包 javax.servlet 不存在”说明代码里还有老包名没改完。全部改完之后再打完整包避免每次都在打包阶段被中断。datax-web 的前端一般也是构建后甚至打进后端 static 目录的。如果你是前端、后端一起构建记得重新构建前端 dist 产物并确认产物目录和你后端静态资源路径一致。我见过只升后端不重新打前端包结果访问登录页 404 的情况不是后端的问题是前端文件没了。4.2 启动时的数据库和中间件核对编译通过只是第一步真正启动时候才会暴露一堆运行期问题。数据库这块老项目常用的是com.mysql:mysql-connector-java坐标这个坐标在 Boot 3 下虽然还能拉到包但新版本 MySQL 官方已经改为com.mysql:mysql-connector-j建议直接更换并且版本至少 8.0.33 以上配合 MySQL 8.0.36 比较稳。数据源连接串也要检查一下。MySQL 8 默认认证插件是 caching_sha2_password如果连接串里没有启用 allowPublicKeyRetrieval在非 SSL 连接下经常会报公钥检索失败连接串里加上allowPublicKeyRetrievaltrue基本能解决。我这边最后稳定的配置大概是这个样子spring: datasource: url: jdbc:mysql://127.0.0.1:3306/datax_web?useUnicodetruecharacterEncodingutf8useSSLfalseallowPublicKeyRetrievaltrueserverTimezoneAsia/Shanghai driver-class-name: com.mysql.cj.jdbc.Driver username: root password: xxxxxx data: redis: host: 127.0.0.1 port: 6379 database: 0启动时重点观察日志里的 Mapper 映射记录和数据源初始化情况不要看到“Started ... in x seconds”就觉得万事大吉Spring Boot 的启动成功不代表所有 Bean 都初始化正确很多懒加载的 Bean 要等第一次调用才报错。4.3 跑通一条 DataX 同步任务才算升级完成服务能起来只是第一阶段真正的验收标准是在新版本下完整跑通一条 DataX 同步任务。我建议用最小场景来测构建一个 MySQL 到 MySQL 的同步任务手动运行然后观察执行器是否正常拉取任务、是否成功调用 datax.py、日志是否能正常回写到 Web 控制台。这个环节最容易出问题的不是 datax-web 本身而是执行器节点上的环境配置。datax-web 的执行器需要知道 DataX 的安装路径通常要配置 datax 的 home 目录和 python 环境变量。你升级的是控制面底层 DataX 脚本版本不用动但环境变量要重新确认一遍。另外一个常见的关联问题是调度系统如果你公司用 DolphinScheduler 统一调度它本身是可以调 DataX 任务的通常用自带的 DataX 节点直接跑 datax.py也可以通过脚本去调 datax-web 的 API。升级 datax-web 和 DolphinScheduler 之间没有硬冲突但要小心两边 JDK 环境变量别被覆盖成同一个版本尤其当两台服务部署在同一台机器时。5. 常见问题速查表与升级后的几个细节5.1 编译期和启动期问题速查下面这个表是我升级过程中真实遇到的报错和对应解法基本可以覆盖老 Boot 项目升 Boot 3 的大部分问题报错现象根本原因处理方式Unable to load cache item / InaccessibleObjectExceptionJDK 17 模块强封装反射被拦截启动脚本加 --add-opensjava.lang.NoClassDefFoundError: javax/servlet/…代码或依赖还在用旧 Servlet API全局替换为 jakarta.servlet并确认 servlet-api 坐标java.lang.ClassNotFoundException: javax.xml.bind.JAXBExceptionJDK 8 内置 JAXBJDK 11 已移除引入 jakarta.xml.bind-api jaxb-runtimeFailed to introspect Class [...] from ClassLoader依赖版本太老比如 MyBatis-Plus 3.4升级 MyBatis-Plus 至 3.5.3用 boot3 starterantMatchers not found / is deprecatedSpring Security 6 API 变动改为 authorizeHttpRequests requestMatchersThis application has no explicit mapping for /error前端静态资源路径或拦截器顺序问题检查 WebMvcConfigurer 的 addResourceHandlers 配置MySQL caching_sha2_password authentication failedMySQL 8 默认认证插件连接串加 allowPublicKeyRetrievaltrueCannot register WebSocket endpointjavax.websocket 和 jakarta.websocket 冲突清理老依赖按 jakarta 重新编译5.2 升级完还要做的三件事第一把整个团队的开发环境统一到新版本。仅改你本机的 IDEA Project SDK 和 Maven 编译器还不够要把 CI 流水线里的 JDK 版本、Maven 配置、Docker 基础镜像全部改成 JDK 17否则开发环境正常、测试环境编译失败的情况会反复出现。用 IDEA 创建 Spring Boot 3 项目的时候默认模板也会用 JDK 17说明这已经是新常态。第二给数据库表做一次兼容性检查。datax-web 的官方表结构基本可以沿用但你二次开发可能加过字段或表升级之后要跑一遍 SQL 校验尤其是 datetime 和 text 类型字段在不同 MySQL 版本下的行为差异。如果数据库里已经有大量任务配置强烈建议升级前做一次全量备份。第三把监控补上。切换 JDK 17 和 Boot 3 之后JVM 的内存模型和默认 GC 行为有变化建议通过 spring-boot-starter-actuator 把 JVM 指标接进 Prometheus重点看 Metaspace、老年代和线程数不然流量上来之后才发现内存涨得比老版本快排查成本很高。5.3 几个值得记下来的经验升级顺序上我强烈建议分两步走先单独在 JDK 17 下编译老 Boot 2.3 代码把因为 JDK 版本引起的报错先收集一轮然后再切换到 Boot 3 依赖去处理框架层的问题。两个大变量叠加在一起的话出了一行报错你很难判断到底是 JDK 引起的还是 Spring Boot 3 引起的。javax 到 jakarta 的替换别只盯着自己写的 Java 文件也要排查依赖传递。用mvn dependency:tree查一下有没有老 jar 把 javax.servlet-api 或 javax.websocket-api 带了进来有的话直接在 pom 里 exclude 掉。这种隐藏依赖最烦人因为它不在你的代码里编译期不报错运行期才出问题。安全配置升级的时候不要照抄别人的博客配置尤其是 URL 规则。把你项目里现在的所有接口路径列一张表一条一条对应到 Security 6 的 requestMatchers 上漏一个接口就可能导致整个管理页面登录失效或者静态资源全部 403。最后说点个人感受。这种升级真正难的地方从来不是 Spring Boot 3 的新 API 有多难学而是老项目里那些在 JDK 8 Boot 2.x 时代一直没爆发的“小毛病”会在新版本下集中冒出来。我这次白天改代码、晚上盯编译花了差不多一周收获最大的不是版本号终于变了而是把项目里的自定义代码彻底梳理了一遍。如果你也在折腾同样的事别慌按照“盘点依赖、统一 JDK、替换包名、调整安全框架、回归数据同步任务”的顺序来问题总能一个个啃完。特别提醒一句升级前记得把 datax-web 里所有任务配置和调度计划导出一份备份别问我为什么知道要备份。 
长河君 · 2026/10/3 17:23:37 · 阅读 1.2k DataX-Web迁移实战：Spring Boot 2到3与JDK 8到17升级全指南
如果你正在接手或维护一套 datax-web社区里通常写成 datax-web也有叫 datax web 的并且最近被要求把它从 Spring Boot 2.x 升到 Spring Boot 3、JDK 8 升到 JDK 17那你大概率已经感受到了那种“说大不大、说小不小”的升级焦虑。我这次升级的是团队内部基于 datax-web 二次开发的调度和同步平台老代码一路从 Spring Boot 2.1 走到 2.3JDK 8 用了很多年直到新部署的机器镜像默认只给 JDK 17、部分配套组件也要求新版兼容才终于下定决心做一次整体迁移。datax-web 的本质是给阿里 DataX 套了一层 Web 管控面解决的是任务可视化配置、手动/定时触发、执行日志查看、权限管理这些事底层真正跑数据同步的还是 DataX 的 Python 脚本。所以升级过程中最难啃的不是 DataX而是外面这层 Spring Boot 应用。这篇文章按照我实际改造的顺序来写老项目盘点、版本路线确定、javax/jakarta 迁移、依赖矩阵、代码实操、构建排错、回归验证最后是一份可以直接抄的常见问题清单。适合正在做老 Spring Boot 项目升级的人参考也适合对 Spring Boot 3 和 Spring Security 6 迁移还没概念的同学当案例看。1. 升级前的技术摸底先别急着改 pom.xml1.1 先搞清楚你手里的是哪个 datax-web 分支datax-web 这个项目社区里有好几个流传版本比较常见的是 WeiYe-Jing/datax-web 这个仓库以及后来各种公司 fork 出来继续魔改的增强分支。这些版本的模块划分大体一致一个 web 控制台负责用户和任务管理一个 executor 执行器负责拉取任务并调用 datax.py前端一般是 Vue Element UI 构建的静态页面。但具体到你手里的代码内部包名、自定义功能、部署方式可能千差万别。我这次拿到的是一套基于 2.x 老分支的二次开发版本登录模块自己改了 JWT 逻辑任务调度基于 Quartz部署方式是打 jar 包然后用 supervisor 托管完全没有用官方推荐的 Docker 方式。如果你手里的也是这种“祖传代码”我建议升级前先花半天把模块边界理清楚至少要知道自定义代码集中在哪个模块、前端产物是打进 Spring Boot 的 static 目录还是单独用 Nginx 托管、有没有外部系统通过 API 在调用 datax-web 的接口。这些因素会直接影响你的升级范围。1.2 升级前必须列清楚的检查清单老项目升级最怕的是“打开 IDE 到处报错”根本原因是依赖太多、版本太乱。我建议先做一次全量盘点把下面这张表填完再动手目标运行环境JDK 版本、操作系统位数、是否有特殊安全基线比如必须用非 root 运行。数据库连接池与驱动用的是什么连接池MySQL 驱动是 com.mysql:mysql-connector-java 还是新坐标。安全认证方式Spring Security、Shiro、JWT 过滤器还是数据库表硬编码账号。任务调度框架Quartz、xxl-job还是自己写的 Timer 线程池。API 文档组件是否用了 springfox SwaggerBoot 3 下 springfox 基本不可用。前端产物登录页、任务配置页是否依赖老接口返回结构。反射和序列化代码里有没有 Fastjson、Gson 对泛型 TypeReference 的使用。外部中间件Redis、ES、MQ哪些是强依赖哪些启动时连不上也不用挂。这些内容看着琐碎但决定你之后是“半天搞定”还是“调一周”。我自己就是没提前登记 WebSocket 的使用场景结果升级到 Spring Boot 3 之后被 javax.websocket 的依赖冲突卡了两个小时。2. JDK 17 和 Spring Boot 3版本路线一次性定清楚2.1 为什么是 JDK 17 而不是继续留在 JDK 8Spring Boot 3 的底层是 Spring Framework 6而 Spring Framework 6 从设计上就把 Java 17 作为基线版本这意味着你想用 Boot 3就必须先把 JDK 升到 17 或更高。JDK 17 又是 LTS 长期支持版本新环境默认装的就是它老应用直接跑在 JDK 17 上老框架的反射、字节码代理很容易触发模块化封装问题所以与其在 JDK 17 上继续跑老 Boot 2.3 去补各种 add-opens不如直接连框架一起升级。如果你在 Windows 或者 Linux 上装 JDK 17步骤并不复杂下载对应的 .tar.gz 或安装包配置 JAVA_HOME 和 PATH然后在启动脚本里显式写死 /path/to/jdk17/bin/java。这里特别提醒一点服务器上如果同时存在 JDK 8 和 JDK 17千万不要依赖全局 PATH否则日志里会出现“Unsupported major.minor version 61.0”这种没头没脑的提示。部署脚本里写死绝对路径是最稳妥的。2.2 javax 到 jakarta 的包名大迁移这是 Spring Boot 3 升级最明显、也最费手的一个变化。Java EE 移交到 Eclipse 基金会之后命名空间从 javax 变成了 jakartaSpring Boot 3 内置的 Servlet 容器已经是 Tomcat 10.1 / Jetty 11 / Undertow 2.2对应的是 Jakarta EE 9 API。所以老代码里的 javax.servlet.* 在编译期直接就找不到类了。我实际遇到的主要是这几个包的替换老包新包说明javax.servlet.*jakarta.servlet.*Filter、Servlet、HttpServletRequest 等javax.validation.*jakarta.validation.*参数校验注解javax.annotation.PostConstructjakarta.annotation.PostConstruct生命周期注解javax.websocket.*jakarta.websocket.*WebSocket 端点和会话javax.persistence.*jakarta.persistence.*如果项目用了 JPAjavax.transaction.*jakarta.transaction.*事务相关 API替换方法我用的是全局搜索兼顾人工确认。IDE 自带 Refactor 功能比如 IDEA 的 Java EE Migration 流程能帮你改一部分但代码里如果是字符串拼接、XML 配置、SPI 文件里写了 javax 全类名就得自己排查了。最靠谱的命令是grep -R javax\. src/把所有命中一条条过一遍宁可多花半小时也不要漏掉某个隐藏在常量里的字符串。2.3 依赖版本矩阵照着这张表挑版本升级依赖不是把所有版本号往大了调就行关键是要确定各个库对 Spring Boot 3 / JDK 17 的适配情况。我这次整理出一套验证过能配合使用的版本组合你直接照抄问题不大但要根据自己项目实际微调组件老版本典型值升级后建议值备注Spring Boot2.3.x3.2.x / 3.3.x3.2 以上对 JDK 17 支持成熟JDK817不要用 21 除非你想当小白鼠MyBatis-Plus3.4.x3.5.5推荐用专门适配 boot3 的 startermysql-connectorcom.mysql:mysql-connector-java:8.0.2xcom.mysql:mysql-connector-j:8.0.33注意坐标已经变了springfox-swagger2.9.x / 3.0.0springdoc-openapi 2.xspringfox 老版本在 Boot 3 下基本不可用Lombok1.18.201.18.30老版本不支持 JDK 17 编译Quartz2.3.x2.3.2 可用但要用 spring-boot-starter-quartz 统一管理Fastjson1.2.681.2.83 或 fastjson2老版本在 JDK 17 下反射兼容性差如果你项目里用了 Redis还要注意 spring-boot-starter-data-redis 在 Boot 3 下依赖的是 Lettuce 6.1老项目的连接池配置项有一些变化启动后要重点看日志里 Redis 连接是否正常输出。3. 核心代码改造实操安全、持久层、WebSocket、启动参数3.1 Spring Security 6WebSecurityConfigurerAdapter 已经彻底没了Spring Security 6 改动最大的地方是 WebSecurityConfigurerAdapter 这个基类被删掉了以前写一坨继承类的配置方式全部要改成 SecurityFilterChain Bean。如果你项目里用的是 Shiro影响没这么大但只要涉及 Spring Security 就要重写。我这次改造的登录模块刚好是 JWT Security 的组合踩的坑基本都集中在这块。新标准写法是定义 SecurityFilterChain Bean我直接贴一段可以用的配置Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http.csrf(csrf - csrf.disable()) .authorizeHttpRequests(auth - auth .requestMatchers(/login, /static/**, /api/auth/**).permitAll() .anyRequest().authenticated() ) .formLogin(form - form.loginPage(/login).permitAll()) .logout(logout - logout.logoutSuccessUrl(/login)) .sessionManagement(session - session .sessionCreationPolicy(SessionCreationPolicy.STATELESS) ); return http.build(); } Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }注意几个关键差异旧版的.antMatchers(/**)变成了.requestMatchers(/**)旧版的.authorizeRequests()变成了.authorizeHttpRequests()旧版的.and()链式调用全部移除。URL 匹配规则也有细节变化旧的/user/*只匹配一级路径新写法推荐用/user/**我实际测试中前者在 Security 6 下的匹配行为有坑。另外过滤器顺序非常重要如果你自定义了 JWT 认证过滤器记得用http.addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)明确指定位置否则会出现“该登录的没登录不该拦的全拦了”的诡异现象。3.2 MyBatis-Plus 和 MyBatis 在 Boot 3 下的兼容处理如果你的老项目用了 MyBatis-Plus 3.4.x直接升级到 Spring Boot 3 后启动时会报 “Failed to introspect Class” 或 “ClassNotFound” 之类的错误本质原因是老版本的 starter 还在走 Spring Boot 2 的自动装配机制。官方从 3.5.3 开始适配 Boot 3我这边用的是 3.5.5实测比较稳。另外一个坑是坐标MyBatis-Plus 官方后来提供了专门给 Spring Boot 3 用的 starter名字叫 mybatis-plus-spring-boot3-starter引入的时候别还是引入原来的 mybatis-plus-boot-starter。还有几个容易忽略的点分页插件、乐观锁插件这些内部 Bean 在 Boot 3 下初始化时机有变化多个数据源时尤其容易因为初始化顺序问题导致 Mapper 扫描不到。如果项目里自己定义过 SqlSessionFactory 或 MybatisSqlSessionFactoryBean建议把所有 Mapper 路径和类型别名重新核对一遍。我这次就遇到过 Mapper XML 文件里写了旧包名的 parameterType编译不报错启动也不报错但运行时任务列表接口直接 500最后排查半天才发现是 XML 里的全限定类名还带 javax。3.3 WebSocket 和 Servlet 容器相关的替换datax-web 这类管控平台经常用 WebSocket 向前端推送执行日志升级过程中这一块也很容易出问题。首先要做的还是把代码里的javax.websocket.*全部替换成jakarta.websocket.*包括ServerEndpoint注解和WebSocketContainer这些。其次要确认依赖坐标Spring Boot 3 工程里建议直接用spring-boot-starter-websocket它会自动带出兼容 Jakarta API 的 Tomcat 包。如果你用的是独立 Tomcat 部署 war 包而不是可执行 jar升级后还要特别注意 servlet-api 冲突。我遇到过“本地启动一切正常放到 Tomcat 上就报 WebSocket endpoint 无法注册”的情况最后是删掉了打包产物里混入的旧 javax.websocket-api 才解决。顺序上建议先跑可执行 jar稳定了再考虑 war 部署能少踩一半坑。3.4 JVM 启动参数--add-opens 是绕不开的JDK 17 对内部的强封装比 JDK 8 严格很多Spring 的 CGLIB 代理、MyBatis-Plus 对实体字段的反射、Fastjson 处理泛型反序列化都可能在运行期出现InaccessibleObjectException。我这边最终在启动脚本里加了一组 add-opens 参数覆盖了常见的反射场景贴出来供参考JAVA_OPTS -server -Xms1024m -Xmx2048m -XX:MaxMetaspaceSize512m --add-opensjava.base/java.langALL-UNNAMED --add-opensjava.base/java.lang.invokeALL-UNNAMED --add-opensjava.base/java.lang.reflectALL-UNNAMED --add-opensjava.base/java.ioALL-UNNAMED --add-opensjava.base/java.netALL-UNNAMED --add-opensjava.base/java.utilALL-UNNAMED --add-opensjava.base/java.util.concurrentALL-UNNAMED --add-opensjava.base/java.textALL-UNNAMED --add-opensjava.base/java.timeALL-UNNAMED --add-opensjava.sql/java.sqlALL-UNNAMED java $JAVA_OPTS -jar datax-web-*.jar如果你是 Windows 环境启动脚本里把写法换成set JAVA_OPTS...其他内容一样。这些参数加上去对正常逻辑没有副作用属于“宁可多开也不要启动到一半挂掉”的保险做法。如果你用的是高版本 Spring Boot 或者某些库升级后已经适配了模块化系统可以逐步删掉不用的项但没必要一开始就精简。3.5 自动装配机制和配置文件迁移老项目如果自己写过 Spring Boot 自动配置类升级时要注意 Spring Boot 3 已经不再读取META-INF/spring.factories里配置的自动装配类必须新建META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件把自动配置类的全限定名写进去。这个改动非常隐蔽因为如果只是普通 Configuration 注解类启动时仍然生效只有自动装配类的加载方式变了。配置项方面Spring Boot 3 对 ConfigurationProperties 的绑定校验更严格类型不匹配会直接启动失败而不是忽略。我用下来最大的感受是老项目里那些约定俗成的配置前缀如果之前没写规范升级后往往会浮出水面。比如spring.redis.*改成spring.data.redis.*这个变化不知道坑了多少老项目你回头看看自己的 application.yml是不是还在用spring.redis.host4. 构建、启动与 DataX 任务回归4.1 先让编译干净跑通升级代码改完之后第一件要做的事不是启动服务而是把整个工程在 JDK 17 下编译通过。我用的是 Maven命令很简单mvn clean package -Dmaven.test.skiptrue如果模块很多建议先mvn clean compile快速暴露出所有 javac 编译错误重点是 javax 相关 import。如果编译时报 “程序包 javax.servlet 不存在”说明代码里还有老包名没改完。全部改完之后再打完整包避免每次都在打包阶段被中断。datax-web 的前端一般也是构建后甚至打进后端 static 目录的。如果你是前端、后端一起构建记得重新构建前端 dist 产物并确认产物目录和你后端静态资源路径一致。我见过只升后端不重新打前端包结果访问登录页 404 的情况不是后端的问题是前端文件没了。4.2 启动时的数据库和中间件核对编译通过只是第一步真正启动时候才会暴露一堆运行期问题。数据库这块老项目常用的是com.mysql:mysql-connector-java坐标这个坐标在 Boot 3 下虽然还能拉到包但新版本 MySQL 官方已经改为com.mysql:mysql-connector-j建议直接更换并且版本至少 8.0.33 以上配合 MySQL 8.0.36 比较稳。数据源连接串也要检查一下。MySQL 8 默认认证插件是 caching_sha2_password如果连接串里没有启用 allowPublicKeyRetrieval在非 SSL 连接下经常会报公钥检索失败连接串里加上allowPublicKeyRetrievaltrue基本能解决。我这边最后稳定的配置大概是这个样子spring: datasource: url: jdbc:mysql://127.0.0.1:3306/datax_web?useUnicodetruecharacterEncodingutf8useSSLfalseallowPublicKeyRetrievaltrueserverTimezoneAsia/Shanghai driver-class-name: com.mysql.cj.jdbc.Driver username: root password: xxxxxx data: redis: host: 127.0.0.1 port: 6379 database: 0启动时重点观察日志里的 Mapper 映射记录和数据源初始化情况不要看到“Started ... in x seconds”就觉得万事大吉Spring Boot 的启动成功不代表所有 Bean 都初始化正确很多懒加载的 Bean 要等第一次调用才报错。4.3 跑通一条 DataX 同步任务才算升级完成服务能起来只是第一阶段真正的验收标准是在新版本下完整跑通一条 DataX 同步任务。我建议用最小场景来测构建一个 MySQL 到 MySQL 的同步任务手动运行然后观察执行器是否正常拉取任务、是否成功调用 datax.py、日志是否能正常回写到 Web 控制台。这个环节最容易出问题的不是 datax-web 本身而是执行器节点上的环境配置。datax-web 的执行器需要知道 DataX 的安装路径通常要配置 datax 的 home 目录和 python 环境变量。你升级的是控制面底层 DataX 脚本版本不用动但环境变量要重新确认一遍。另外一个常见的关联问题是调度系统如果你公司用 DolphinScheduler 统一调度它本身是可以调 DataX 任务的通常用自带的 DataX 节点直接跑 datax.py也可以通过脚本去调 datax-web 的 API。升级 datax-web 和 DolphinScheduler 之间没有硬冲突但要小心两边 JDK 环境变量别被覆盖成同一个版本尤其当两台服务部署在同一台机器时。5. 常见问题速查表与升级后的几个细节5.1 编译期和启动期问题速查下面这个表是我升级过程中真实遇到的报错和对应解法基本可以覆盖老 Boot 项目升 Boot 3 的大部分问题报错现象根本原因处理方式Unable to load cache item / InaccessibleObjectExceptionJDK 17 模块强封装反射被拦截启动脚本加 --add-opensjava.lang.NoClassDefFoundError: javax/servlet/…代码或依赖还在用旧 Servlet API全局替换为 jakarta.servlet并确认 servlet-api 坐标java.lang.ClassNotFoundException: javax.xml.bind.JAXBExceptionJDK 8 内置 JAXBJDK 11 已移除引入 jakarta.xml.bind-api jaxb-runtimeFailed to introspect Class [...] from ClassLoader依赖版本太老比如 MyBatis-Plus 3.4升级 MyBatis-Plus 至 3.5.3用 boot3 starterantMatchers not found / is deprecatedSpring Security 6 API 变动改为 authorizeHttpRequests requestMatchersThis application has no explicit mapping for /error前端静态资源路径或拦截器顺序问题检查 WebMvcConfigurer 的 addResourceHandlers 配置MySQL caching_sha2_password authentication failedMySQL 8 默认认证插件连接串加 allowPublicKeyRetrievaltrueCannot register WebSocket endpointjavax.websocket 和 jakarta.websocket 冲突清理老依赖按 jakarta 重新编译5.2 升级完还要做的三件事第一把整个团队的开发环境统一到新版本。仅改你本机的 IDEA Project SDK 和 Maven 编译器还不够要把 CI 流水线里的 JDK 版本、Maven 配置、Docker 基础镜像全部改成 JDK 17否则开发环境正常、测试环境编译失败的情况会反复出现。用 IDEA 创建 Spring Boot 3 项目的时候默认模板也会用 JDK 17说明这已经是新常态。第二给数据库表做一次兼容性检查。datax-web 的官方表结构基本可以沿用但你二次开发可能加过字段或表升级之后要跑一遍 SQL 校验尤其是 datetime 和 text 类型字段在不同 MySQL 版本下的行为差异。如果数据库里已经有大量任务配置强烈建议升级前做一次全量备份。第三把监控补上。切换 JDK 17 和 Boot 3 之后JVM 的内存模型和默认 GC 行为有变化建议通过 spring-boot-starter-actuator 把 JVM 指标接进 Prometheus重点看 Metaspace、老年代和线程数不然流量上来之后才发现内存涨得比老版本快排查成本很高。5.3 几个值得记下来的经验升级顺序上我强烈建议分两步走先单独在 JDK 17 下编译老 Boot 2.3 代码把因为 JDK 版本引起的报错先收集一轮然后再切换到 Boot 3 依赖去处理框架层的问题。两个大变量叠加在一起的话出了一行报错你很难判断到底是 JDK 引起的还是 Spring Boot 3 引起的。javax 到 jakarta 的替换别只盯着自己写的 Java 文件也要排查依赖传递。用mvn dependency:tree查一下有没有老 jar 把 javax.servlet-api 或 javax.websocket-api 带了进来有的话直接在 pom 里 exclude 掉。这种隐藏依赖最烦人因为它不在你的代码里编译期不报错运行期才出问题。安全配置升级的时候不要照抄别人的博客配置尤其是 URL 规则。把你项目里现在的所有接口路径列一张表一条一条对应到 Security 6 的 requestMatchers 上漏一个接口就可能导致整个管理页面登录失效或者静态资源全部 403。最后说点个人感受。这种升级真正难的地方从来不是 Spring Boot 3 的新 API 有多难学而是老项目里那些在 JDK 8 Boot 2.x 时代一直没爆发的“小毛病”会在新版本下集中冒出来。我这次白天改代码、晚上盯编译花了差不多一周收获最大的不是版本号终于变了而是把项目里的自定义代码彻底梳理了一遍。如果你也在折腾同样的事别慌按照“盘点依赖、统一 JDK、替换包名、调整安全框架、回归数据同步任务”的顺序来问题总能一个个啃完。特别提醒一句升级前记得把 datax-web 里所有任务配置和调度计划导出一份备份别问我为什么知道要备份。