Spring6升级后替换aqapi为aqapi-jakarta，Java17编译失败

问题背景 #

将Spring Boot 2（对应Spring 5）升级到Spring Boot 3（对应Spring 6）后，项目会切换到Jakarta EE 9+规范，原有的com.oracle.database.messaging:aqapi依赖因ConnectionFactory类从javax包迁移到jakarta包出现兼容性问题。换成官方提供的com.oracle.database.messaging:aqapi-jakarta依赖后，在Java 17环境下编译失败，出现两类相似报错：

• createShardingKeyBuilder() in cannot implement createShardingKeyBuilder() in javax.sql.CommonDataSource return type oracle.jdbc.OracleShardingKeyBuilder is not compatible with java.sql.ShardingKeyBuilder
• createShardingKeyBuilder in oracle.ucp.jdbc.PoolDataSource clashes with createShardingKeyBuilder in javax.sql.CommonDataSource

根本原因 #

这个冲突源于Oracle JDBC/UCP组件版本与Jakarta EE规范、Java 17不匹配：旧版本的Oracle JDBC/UCP实现的是javax.sql.CommonDataSource中的createShardingKeyBuilder方法，返回Oracle自定义的OracleShardingKeyBuilder；但Java 17及Jakarta EE 9+环境下，该方法要求返回标准的java.sql.ShardingKeyBuilder，两者类型不兼容导致编译报错。

解决方案 #

1. 升级Oracle JDBC和UCP依赖版本 #

使用适配Jakarta EE 9+且支持Java 17的Oracle JDBC和UCP版本，推荐Oracle Database 21c及以上版本的驱动，Maven依赖示例：

<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc11</artifactId>
    <version>21.13.0.0</version>
</dependency>
<dependency>
    <groupId>com.oracle.database.ucp</groupId>
    <artifactId>ucp</artifactId>
    <version>21.13.0.0</version>
</dependency>

新版本已适配Jakarta EE规范，修复了createShardingKeyBuilder方法的返回类型兼容性问题。

2. 保持AQAPI-Jakarta版本与JDBC版本一致 #

aqapi-jakarta的版本必须和Oracle JDBC驱动版本匹配，避免版本差异引发新问题：

<dependency>
    <groupId>com.oracle.database.messaging</groupId>
    <artifactId>aqapi-jakarta</artifactId>
    <version>21.13.0.0</version>
</dependency>

3. 清理依赖冲突 #

执行依赖分析命令排查并排除旧版javax相关的JDBC/UCP依赖，确保所有组件都是Jakarta兼容版本：

mvn dependency:tree

若发现旧版本依赖，通过<exclusions>标签排除，示例：

<dependency>
    <!-- 引入旧版JDBC的第三方依赖 -->
    <groupId>xxx</groupId>
    <artifactId>xxx</artifactId>
    <exclusions>
        <exclusion>
            <groupId>com.oracle.database.jdbc</groupId>
            <artifactId>ojdbc8</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.oracle.database.ucp</groupId>
            <artifactId>ucp</artifactId>
        </exclusion>
    </exclusions>
</dependency>

验证步骤 #

1. 刷新项目依赖，确认所有相关组件都是指定的新版本
2. 重新编译项目，检查是否仍存在createShardingKeyBuilder相关编译错误
3. 启动项目，验证AQ功能是否正常运行

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