父类向下转型为子类时通过instanceof校验却抛出ClassCastException

你遇到的核心问题是JPA查询返回的是User实体类的实例，而非其子类CustomUserDetails的实例——哪怕你以为通过了instanceof校验，直接向下转型也必然抛出异常。下面分场景给你具体解决方案：

场景1：CustomUserDetails不是JPA实体（仅作为Spring Security的UserDetails实现） #

如果CustomUserDetails只是用来封装Spring Security所需用户信息的类，不是数据库映射的实体，那你不能直接把JPA查询到的User实例强制转型为它，而是需要手动将User的属性复制到CustomUserDetails对象中：

public CustomUserDetails findByUsername(String username) { 
    // 查询得到User实体实例
    User user = em.createQuery("from User where username = :username", User.class)
        .setParameter("username", username)
        .getSingleResult(); 
    
    // 手动初始化CustomUserDetails并复制属性
    CustomUserDetails customUserDetails = new CustomUserDetails();
    customUserDetails.setId(user.getId());
    customUserDetails.setUsername(user.getUsername());
    customUserDetails.setPassword(user.getPassword());
    // 复制Spring Security所需的权限等其他字段
    customUserDetails.setAuthorities(convertToAuthorities(user.getRoles()));
    
    return customUserDetails;
}

更优雅的方式是给CustomUserDetails添加一个接收User对象的构造方法：

// 在CustomUserDetails类中新增构造方法
public CustomUserDetails(User user) {
    this.id = user.getId();
    this.username = user.getUsername();
    this.password = user.getPassword();
    // 处理权限等业务逻辑
    this.authorities = convertToAuthorities(user.getRoles());
}

// 仓库层直接调用构造方法
CustomUserDetails customUserDetails = new CustomUserDetails(user);

场景2：CustomUserDetails是JPA实体（继承自User实体） #

如果CustomUserDetails本身是JPA实体类，且与User是继承关系，你需要先确保JPA的继承映射配置正确：

• 在父类User上添加@Inheritance注解，指定继承策略（比如SINGLE_TABLE、JOINED）
• 在CustomUserDetails类上添加@Entity注解

之后修改JPQL查询，直接返回CustomUserDetails实例：

CustomUserDetails user = em.createQuery("from CustomUserDetails where username = :username", CustomUserDetails.class)
    .setParameter("username", username)
    .getSingleResult();

如果需要查询所有User的子类实例（包括CustomUserDetails），可以保留原查询，再通过instanceof校验后转型：

User user = em.createQuery("from User where username = :username", User.class)
    .setParameter("username", username)
    .getSingleResult();

// 此时若查询结果是CustomUserDetails实例，instanceof会返回true，转型不会报错
if (user instanceof CustomUserDetails) {
    CustomUserDetails customUserDetails = (CustomUserDetails) user;
    // 后续业务逻辑
}

为什么会出现“通过instanceof校验还抛异常”？ #

如果你的代码确实通过了instanceof校验但仍报错，大概率是校验的对象和转型的对象不是同一个，比如错误示例：

// 错误：校验的是新创建的customUserDetails，不是查询返回的user
CustomUserDetails customUserDetails = new CustomUserDetails();
if (customUserDetails instanceof CustomUserDetails) {
    // 这里转型的是User实例，自然抛出异常
    customUserDetails = (CustomUserDetails) user;
}

一定要确保instanceof校验的是你要转型的那个对象：

// 正确写法
User user = ...; // JPA查询结果
if (user instanceof CustomUserDetails) {
    CustomUserDetails customUserDetails = (CustomUserDetails) user;
}

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