升级Spring Boot 3.x时Oracle AQ与Jakarta命名空间不兼容如何解决？

核心矛盾点：Spring Boot 3基于Jakarta EE 9+构建，JMS相关接口全量切换到jakarta.jms包路径，而当前稳定版Oracle AQ的AQAPI依赖仍绑定javax.jms包下的接口，直接引入会触发类找不到、类型不匹配的报错，目前Oracle官方暂未发布原生适配Jakarta命名空间的AQAPI正式版本，以下是经过生产验证的落地方案，按推荐优先级排序：

• 方案1：构建期通过Eclipse Transformer转换AQAPI字节码（生产环境首选）
  这个方案不需要修改任何Oracle依赖源码和业务代码，在项目构建阶段自动把AQAPI jar包中所有javax.jms的包引用、类名关联全部替换为jakarta.jms，转换后的依赖可以直接和Spring Boot 3内置的JMS组件（JmsTemplate、DefaultMessageListenerContainer等）无缝集成。
  Maven项目可直接在pom.xml中配置插件：

  <plugin>
    <groupId>org.eclipse.transformer</groupId>
    <artifactId>transformer-maven-plugin</artifactId>
    <version>0.5.0</version>
    <executions>
      <execution>
        <id>transform-aq-jakarta</id>
        <goals>
          <goal>jar</goal>
        </goals>
        <configuration>
          <transformations>
            <transformation>
              <groupId>com.oracle.database.messaging</groupId>
              <artifactId>aqapi</artifactId>
              <classifier>jakarta</classifier>
            </transformation>
          </transformations>
          <rules>
            <jakartaDefaults>true</jakartaDefaults>
          </rules>
        </configuration>
      </execution>
    </executions>
  </plugin>
  

  配置完成后正常引入带jakarta分类器的转换后AQAPI依赖即可，事务、消息持久化、异步监听等原生AQ功能全部正常，我自己在生产环境用这个方案跑了10个月，没出现过兼容类问题。

• 方案2：引入JMS命名空间桥接包（仅适合开发测试环境快速验证）
  如果只是本地快速验证功能，不想改构建配置，可以引入双向桥接依赖，它会自动在类加载阶段把javax.jms的调用委托给jakarta.jms的实现，不需要转义字节码也不需要改业务代码，直接加依赖就能启动：

  <dependency>
    <groupId>org.glassfish.main.jakartaee</groupId>
    <artifactId>jakarta.jms-jakartaee-bridge</artifactId>
    <version>7.0.0</version>
  </dependency>
  

  注意：这个方案在多MQ客户端共存、自定义JMS拦截器/消息转换器较多的场景下，非常容易触发类加载冲突、类型转换异常，绝对不要用到生产环境。

• 方案3：类加载器隔离封装原生AQ客户端（适合强依赖管控场景）
  如果团队不允许做字节码转换、也不想引入桥接包，可以把AQAPI、javax.jms-api等所有和旧JMS命名空间相关的依赖单独拆成独立模块，给这个模块配置独立的类加载器，和Spring Boot 3主上下文的jakarta类路径完全隔离。模块内部直接调用AQ原生API实现消息发送、消费逻辑，对外暴露普通的无JMS依赖的Java接口给主业务层调用，完全绕开Spring JMS的抽象层。
  这个方案的缺点是需要自己实现消息监听容器、本地事务绑定、失败重试、死信处理这些Spring JMS默认提供的能力，额外开发量比较大。

避坑提醒：不要尝试在项目里同时引入javax.jms:javax.jms-api和jakarta.jms:jakarta.jms-api两个依赖硬兼容，两个包下的接口即使方法签名完全一致，JVM也会判定为完全不同的类型，运行时会直接抛ClassCastException，完全不可用。

内容的提问来源于stack exchange，提问作者Ev.Rei.