Hibernate复合主键继承映射报错：UnionSubclass无法转为RootClass如何解决

现有如下JPA实体结构：
基类Setting代码：

@Entity
@IdClass(SettingId.class)
@Table(name = "setting")
@Inheritance(strategy= InheritanceType.TABLE_PER_CLASS)
public class Setting implements Comparable<Setting> {
   
    @Id
    @Column(name = "key_", nullable = false, length = FieldConstants.SETTING_KEY_LENGTH)
    @Enumerated(EnumType.STRING)
    private SettingKey key;

    @Column(name = "value_", nullable = false, length = FieldConstants.SETTING_VALUE_LENGTH)
    private String value;

    @Id
    @Column(name = "type_", nullable = false, length = FieldConstants.SETTING_KEY_LENGTH)
    @Enumerated(EnumType.STRING)
    private SettingType type;
    ...
}

子类PersonSetting继承Setting：

@Entity
@IdClass(PersonSettingId.class)
@Table(name = "person_setting")
public class PersonSetting extends Setting {
    
    @Id
    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "user_id", foreignKey = @ForeignKey(name = "fk_user"))
    private Person person;
    ...
}

其中SettingId是Setting的复合主键类（包含key和type）；PersonSettingId继承SettingId并添加person字段，构成包含key、type、person的复合主键。

运行时抛出异常：UnionSubclass cannot be cast to class org.hibernate.mapping.RootClass

方案一：移除子类的@IdClass注解 #

在TABLE_PER_CLASS继承策略下，Hibernate会将子类视为UnionSubclass而非RootClass，子类无需单独指定@IdClass，父类的主键配置会被继承，同时子类新增的@Id字段会自动纳入复合主键体系。具体操作：

• 删除PersonSetting类上的@IdClass(PersonSettingId.class)注解
• 保留PersonSetting中person字段的@Id注解
• 重写PersonSetting的equals和hashCode方法，基于key、type、person三个字段实现

方案二：改用@EmbeddedId实现复合主键（更规范的继承场景方案） #

1. 修改父类Setting，用@EmbeddedId替代@IdClass：

@Entity
@Table(name = "setting")
@Inheritance(strategy= InheritanceType.TABLE_PER_CLASS)
public class Setting implements Comparable<Setting> {
   
    @EmbeddedId
    private SettingId id;

    @Column(name = "value_", nullable = false, length = FieldConstants.SETTING_VALUE_LENGTH)
    private String value;
    ...
}

2. 将SettingId改为嵌入式主键类：

@Embeddable
public class SettingId implements Serializable {
    @Column(name = "key_", nullable = false, length = FieldConstants.SETTING_KEY_LENGTH)
    @Enumerated(EnumType.STRING)
    private SettingKey key;

    @Column(name = "type_", nullable = false, length = FieldConstants.SETTING_KEY_LENGTH)
    @Enumerated(EnumType.STRING)
    private SettingType type;

    // 必须重写equals和hashCode方法
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        SettingId settingId = (SettingId) o;
        return key == settingId.key && type == settingId.type;
    }

    @Override
    public int hashCode() {
        return Objects.hash(key, type);
    }
}

3. 创建子类的嵌入式主键类PersonSettingId：

@Embeddable
public class PersonSettingId extends SettingId implements Serializable {
    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "user_id", foreignKey = @ForeignKey(name = "fk_user"))
    private Person person;

    // 重写equals和hashCode，包含person字段
    @Override
    public boolean equals(Object o) {
        if (!super.equals(o)) return false;
        PersonSettingId that = (PersonSettingId) o;
        return Objects.equals(person, that.person);
    }

    @Override
    public int hashCode() {
        return Objects.hash(super.hashCode(), person);
    }
}

4. 修改子类PersonSetting使用@EmbeddedId：

@Entity
@Table(name = "person_setting")
public class PersonSetting extends Setting {
    
    @EmbeddedId
    private PersonSettingId id;
    ...
}

关键原因说明 #

TABLE_PER_CLASS策略下，父类和子类的表各自独立存储完整数据，Hibernate将子类映射为UnionSubclass而非根实体（RootClass）。而@IdClass通常用于根实体的复合主键配置，子类单独指定会导致Hibernate的映射逻辑冲突，触发类型转换异常。

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