Play Framework热重载失效：自定义Pac4j扩展类引发类型转换异常

环境信息 #

• Play Framework v2.8.16
• Pac4j v10.0.2（pac4j-http、pac4j-oauth、pac4j-jwt均为4.5.7）
• Java 12
• 多模块Java应用

问题现象 #

自定义CustomJwtProfile继承自Pac4j的JwtProfile：

public class CustomJwtProfile extends org.pac4j.jwt.profile.JwtProfile

应用启动后运行正常，但修改代码触发热重载后，抛出类转换异常：

play.api.PlayException: Execution exception[[ClassCastException: class my.package.CustomJwtProfile cannot be cast to class class my.package.CustomJwtProfile (class my.package.CustomJwtProfile is in unnamed module of loader play.runsupport.DelegatedResourcesClassLoader @2a1321ec; my.package.CustomJwtProfile is in unnamed module of loader play.runsupport.DelegatedResourcesClassLoader @47424930)]]

异常堆栈指向PermissionChecker.check()方法，该类原泛型定义为：

public class PermissionChecker<U extends CustomJwtProfile >

若将泛型约束改为继承父类JwtProfile，则异常消失：

public class PermissionChecker<U extends org.pac4j.jwt.profile.JwtProfile>

原因分析 #

1. Play热重载的类加载机制：Play开发模式下，热重载会创建新的DelegatedResourcesClassLoader加载修改后的类，而旧类加载器生成的实例可能仍保存在Session、缓存等上下文环境中。
2. Pac4j的Profile持久化特性：Pac4j会将认证后的Profile实例存储在Session中，热重载后新类加载器加载的PermissionChecker尝试转换旧类加载器的CustomJwtProfile实例时，JVM因类加载器不同判定为不同类型，抛出转换异常。
3. 多模块类加载隔离：CustomJwtProfile与PermissionChecker分属不同模块，热重载时可能仅其中一个模块的类被重新加载，导致跨模块类型校验出现类加载器不匹配。

解决方案 #

1. 临时规避：调整泛型约束 #

将PermissionChecker的泛型约束改为基于Pac4j的父类JwtProfile而非自定义子类。父类由系统类加载器加载，不会随热重载更新，可避免类加载器差异问题。

2. 禁用特定模块热重载 #

在build.sbt中配置包含CustomJwtProfile的模块，禁止其参与热重载：

lazy val profileModule = (project in file("modules/profile"))
  .settings(
    // 移除热重载钩子
    PlayKeys.playRunHooks := Nil,
    // 取消该模块的文件监听
    watchSources := Nil
  )

3. 热重载时清理旧Profile缓存 #

自定义Play的ApplicationLifecycle钩子，在热重载触发时清理Session中的旧Profile实例：

import play.ApplicationLifecycle;
import play.mvc.Http;
import org.pac4j.play.Constants;

import javax.inject.Singleton;
import java.util.concurrent.CompletableFuture;

@Singleton
public class ProfileCleanupHook implements ApplicationLifecycle {
    @Override
    public CompletableFuture<?> stop() {
        if (Http.Context.current() != null) {
            // 移除Session中存储的Pac4j用户Profile
            Http.Context.current().session().remove(Constants.USER_PROFILES);
        }
        return CompletableFuture.completedFuture(null);
    }
}

在Module.java中绑定该钩子：

import com.google.inject.AbstractModule;

public class Module extends AbstractModule {
    @Override
    protected void configure() {
        bind(ApplicationLifecycle.class).to(ProfileCleanupHook.class).asEagerSingleton();
    }
}

4. 升级依赖版本 #

检查Pac4j 10.x后续版本或Play 2.8.x的更新，新版本可能优化了类加载兼容性，解决热重载时的类实例冲突问题。

验证方式 #

1. 修改代码触发热重载，观察是否再出现ClassCastException；
2. 执行认证流程，验证权限检查逻辑正常运行。

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