从Java8 EE Tomee8迁移至Java11+ Tomee9遇依赖与类找不到问题

核心问题本质 #

Java EE到Jakarta EE的命名空间切换是全量不兼容的，javax.*与jakarta.*属于两套独立的API体系，混合依赖必然引发运行时类加载冲突，这也是你遇到NoClassDefFoundError的根本原因。

分阶段迁移方案（无需批量升级第三方库） #

1. 先保留Java EE API依赖，稳定基础环境 #

不要一开始就全量替换命名空间，先切换到TomEE 9 + JDK 17，但暂时保留Java EE 8的API依赖，确保第三方库兼容性：

<dependency>
    <groupId>org.apache.tomee</groupId>
    <artifactId>javaee-api</artifactId>
    <version>8.0-6</version>
    <scope>provided</scope>
</dependency>

此时像Auth0 mvc-auth-commons 1.9.2这类依赖javax的第三方库能正常工作，不会出现编译冲突。

2. 分模块逐步迁移自有代码到Jakarta命名空间 #

针对自有业务代码，按模块/功能点拆分迁移：

• 先迁移EJB模块：将javax.ejb.*替换为jakarta.ejb.*
• 再迁移Servlet相关代码：将javax.servlet.*替换为jakarta.servlet.*
• 每完成一个模块的迁移，立即做功能测试，避免批量替换引发大面积问题。

3. 引入桥接依赖解决混合阶段的兼容问题 #

当部分代码已迁移到Jakarta、但第三方库仍依赖javax时，引入容器提供的桥接依赖，实现两套API的双向转发：

<!-- Servlet API桥接 -->
<dependency>
    <groupId>org.apache.tomcat</groupId>
    <artifactId>tomcat-jakartaee-migration</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>
<!-- JAX-RS API桥接 -->
<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-jaxrs-migration</artifactId>
    <version>6.2.7.Final</version>
    <scope>provided</scope>
</dependency>

这些桥接依赖会在类加载时自动将javax API的调用转发到Jakarta实现，避免NoClassDefFoundError。

4. 最终全量切换到Jakarta EE API #

当所有自有代码迁移完成，且确认第三方库要么已升级到Jakarta版本、要么通过桥接能稳定运行后，替换API依赖为Jakarta EE 10：

<dependency>
    <groupId>org.apache.tomee</groupId>
    <artifactId>jakartaee-api</artifactId>
    <version>10.0-M1</version>
    <scope>provided</scope>
</dependency>

注意：将scope设为provided，因为TomEE 9本身已包含Jakarta EE的实现，无需打包到应用中。

常见问题针对性处理 #

• ClassNotFoundError: javax/ws/rs/ext/MessageBodyReader：引入上述resteasy-jaxrs-migration桥接依赖即可解决JAX-RS的兼容问题。
• javax/interceptor/InvocationContext找不到：添加CDI桥接依赖：

<dependency>
    <groupId>org.apache.openwebbeans</groupId>
    <artifactId>openwebbeans-jakartaee-migration</artifactId>
    <version>2.0.28</version>
    <scope>provided</scope>
</dependency>

关键注意事项 #

• 绝对不要同时引入javax和Jakarta的同类型API依赖（如同时引入javax.ws.rs-api和jakarta.ws.rs-api），这会直接触发类加载冲突。
• 所有API依赖的scope尽量设为provided，避免与容器自带的实现重复打包。
• 优先使用官方容器提供的桥接工具，不要自行编写兼容代码，避免引入额外风险。

内容的提问来源于stack exchange，提问作者Nephilim