Spring Boot项目中ClientBuilder类转换异常的pom.xml修复方案

在基于Spring Boot 3.1.5的应用中执行以下REST调用代码时，出现ClassCastException：

Client client = ClientBuilder.newClient().register(jacksonMapper);

错误栈信息如下：

java.lang.LinkageError: ClassCastException: attempting to castjar:file:~/.m2/repository/javax/ws/rs/javax.ws.rs-api/2.1.1/javax.ws.rs-api-2.1.1.jar!/javax/ws/rs/client/ClientBuilder.class to jar:file:~/.m2/repository/javax/ws/rs/javax.ws.rs-api/2.1.1/javax.ws.rs-api-2.1.1.jar!/javax/ws/rs/client/ClientBuilder.class
at javax.ws.rs.client.ClientBuilder.newBuilder(ClientBuilder.java:81)
at javax.ws.rs.client.ClientBuilder.newClient(ClientBuilder.java:97)
at com.ibm.cio.snap.dao.oauth.TSAPIOAuthDAO.validateAccessToken(TSAPIOAuthDAO.java:141)
...（省略后续栈跟踪内容）
",
    "message": "ClassCastException: attempting to castjar:file:~/.m2/repository/javax/ws/rs/javax.ws.rs-api/2.1.1/javax.ws.rs-api-2.1.1.jar!/javax/ws/rs/client/ClientBuilder.class to jar:file:~/.m2/repository/javax/ws/rs/javax.ws.rs-api/2.1.1/javax.ws.rs-api-2.1.1.jar!/javax/ws/rs/client/ClientBuilder.class",
    "path": "/api/v1/utilities/configuration"

当前项目pom.xml核心配置：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.5</version>
        <relativePath /> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.ibm.cio</groupId>
    <artifactId>snap</artifactId>
    <version>0.0.1</version>
    <name>snap</name>
    <description>SMS Digital Assistant</description>
    <properties>
        <java.version>17</java.version>
        <avro.version>1.11.3</avro.version>
        <grpc.version>1.60.1</grpc.version>
        <!-- JaCoCo Properties -->
        <jacoco.version>0.8.8</jacoco.version>
        <sonar.dynamicAnalysis>reuseReports</sonar.dynamicAnalysis>
        <sonar.language>java</java>
    </properties>
    <dependencies>
        ...（省略中间依赖内容）
    </dependencies>
    <build>
        ...（省略build配置内容）
    </build>
</project>

核心原因 #

Spring Boot 3.x基于Jakarta EE 9+规范，原JEE体系的javax.*包已全部迁移至jakarta.*命名空间。当前代码依赖的javax.ws.rs-api是JEE时代的旧依赖，与Jakarta EE规范冲突，导致同一类被不同类加载器加载，触发类型转换错误。

pom.xml修改步骤 #

1. 引入兼容的JAX-RS客户端依赖
   添加Spring Boot官方整合的Jersey starter依赖，它适配Jakarta EE规范，与Spring Boot 3.x完全兼容：

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-jersey</artifactId>
   </dependency>
   

2. 清理旧的JAX-RS依赖

   • 若pom.xml中直接引入了javax.ws.rs-api，直接删除该依赖项。
   • 若为间接依赖，通过exclusions排除所有javax.ws.rs相关依赖：

     <dependency>
         <!-- 替换为实际存在冲突的依赖坐标 -->
         <groupId>xxx</groupId>
         <artifactId>xxx</artifactId>
         <exclusions>
             <exclusion>
                 <groupId>javax.ws.rs</groupId>
                 <artifactId>javax.ws.rs-api</artifactId>
             </exclusion>
         </exclusions>
     </dependency>
     

3. 代码适配
   将代码中javax.ws.rs.client.ClientBuilder的引用替换为jakarta.ws.rs.client.ClientBuilder，确保使用Jakarta版本的API。

额外验证步骤 #

• 执行mvn dependency:tree命令，检查依赖树中是否残留javax.ws.rs相关依赖。
• 清理本地Maven仓库中~/.m2/repository/javax/ws/rs目录，避免旧缓存影响。

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