解决SingleTableSubclass无法转换为RootClass的Hibernate类型转换异常

问题场景 #

出现以下异常：

java.lang.ClassCastException: org.hibernate.mapping.SingleTableSubclass cannot be cast to org.hibernate.mapping.RootClass

异常根源在于类结构中存在冲突的@Id注解，对应类结构如下：

1. 抽象类CommonProduct标记为@Entity并定义了@Id字段：

@Entity
@Table(name = "PRODUCTS")
public abstract class CommonProduct<Type extends AbstractProductUnderlying> extends HibernatePersistentObject implements Serializable, UniqueObject {
    @Ignore
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "products_seq")
    @SequenceGenerator(name = "products_seq", sequenceName = "products_seq")
    @Column(name = "productId")
    protected Integer productId;
}

2. 子类Product采用单表继承策略，复用父类的@Id：

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
public class Product extends CommonProduct<ProductUnderlying> {
}

3. 子类ProductHistory对应另一张表，定义了独立的@Id字段：

@Entity(name = "viewProductHistory")
@Table(name = "PRODUCT_HISTORY")
public class ProductHistory extends CommonProduct<ProductUnderlyingHistory> {

    @Id
    @Column(name = "PRODUCT_HISTORY_ID")
    private int ProductHistoryId;
}

问题原因 #

当CommonProduct被标记为@Entity时，它会作为实体继承树的根节点，Hibernate要求整个继承树必须共享同一主键策略。但ProductHistory既继承了这个实体根类，又自定义了独立主键，破坏了单表继承的规则，导致Hibernate在处理映射时出现类型转换冲突。

解决方案 #

将CommonProduct改为映射超类（@MappedSuperclass），而非实体类。这样它仅作为字段复用的基类，每个子类可以独立成为实体并定义自己的主键策略。

修改后的代码示例 #

1. 重构CommonProduct为映射超类：

@MappedSuperclass
public abstract class CommonProduct<Type extends AbstractProductUnderlying> extends HibernatePersistentObject implements Serializable, UniqueObject {
    // 移除@Id注解，仅保留字段映射
    @Column(name = "productId")
    protected Integer productId;

    // 其他共享字段和方法...
}

2. 调整Product类，将继承的productId标记为主键：

@Entity
@Table(name = "PRODUCTS")
public class Product extends CommonProduct<ProductUnderlying> {
    // 重写productId字段并添加主键注解（或在getter上添加）
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "products_seq")
    @SequenceGenerator(name = "products_seq", sequenceName = "products_seq")
    @Column(name = "productId")
    @Override
    public Integer getProductId() {
        return super.getProductId();
    }
}

3. ProductHistory类保持原有主键定义，继承映射超类即可：

@Entity(name = "viewProductHistory")
@Table(name = "PRODUCT_HISTORY")
public class ProductHistory extends CommonProduct<ProductUnderlyingHistory> {

    @Id
    @Column(name = "PRODUCT_HISTORY_ID")
    private int productHistoryId; // 修正变量名符合Java规范

    // 继承自CommonProduct的productId作为普通字段存在
}

其他可选方案 #

如果CommonProduct必须作为实体类存在，可以拆分继承结构：

• 让Product与CommonProduct组成单表继承树（保留原有@Entity和@Id）
• ProductHistory改为继承一个不带@Id的通用基类（而非CommonProduct），通过组合方式复用CommonProduct的字段逻辑

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