Keycloak从23升级到24后SPI事件监听器失效故障排查

问题根源 #

Keycloak 24版本对底层依赖的Resteasy框架做了版本升级和初始化逻辑调整，ResteasyClientBuilderImpl的无参构造函数被隐藏或移除，导致直接实例化该类的代码触发java.util.ServiceConfigurationError。

解决步骤 #

1. 改用Resteasy标准工厂方法创建ClientBuilder #

替换代码中直接实例化ResteasyClientBuilderImpl的逻辑，使用Resteasy提供的标准API获取客户端构建器，这是兼容不同版本的通用方式：

// 原错误代码（Keycloak 23兼容，24报错）
// ResteasyClientBuilder clientBuilder = new ResteasyClientBuilderImpl();

// 修改后的兼容代码
ResteasyClientBuilder clientBuilder = ResteasyClientBuilder.newBuilder();

2. 检查并修正pom.xml依赖配置 #

确保SPI项目中Keycloak和Resteasy相关依赖的范围为provided，避免打包时引入重复依赖与Keycloak内置版本冲突：

<dependencies>
    <!-- Keycloak SPI依赖 -->
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-server-spi</artifactId>
        <version>24.0.4</version>
        <scope>provided</scope>
    </dependency>
    <!-- Resteasy客户端依赖 -->
    <dependency>
        <groupId>org.jboss.resteasy</groupId>
        <artifactId>resteasy-client</artifactId>
        <version>6.2.7.Final</version> <!-- 匹配Keycloak 24内置的Resteasy版本 -->
        <scope>provided</scope>
    </dependency>
</dependencies>

3. 确保SPI类加载隔离 #

Keycloak 24对SPI的类加载机制做了更严格的隔离，需保证SPI jar包中不包含Resteasy的类文件，仅保留自身业务代码。如果之前有自定义类加载逻辑，需移除或调整以使用容器提供的类。

4. 彻底清理并重新部署 #

• 执行mvn clean install清理旧构建产物，重新编译打包SPI jar包
• 替换Keycloak部署目录（如standalone/deployments）中的旧SPI jar包
• 重启Keycloak服务验证修复效果

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