单表继承策略下Hibernate/JPA无法识别子类类型问题排查

问题背景 #

使用Java 11、Spring Boot、MySQL、Liquibase、JPA及Hibernate开发，定义了如下实体类：

@MappedSuperclass
@Data
public class BaseEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String refId = UUID.randomUUID().toString();

}

@Entity
@Table(name = "field_descriptors")
@AttributeOverrides({
    @AttributeOverride(name = "id", column = @Column(name = "field_descriptor_id")),
    @AttributeOverride(name = "refId", column = @Column(name = "field_descriptor_ref_id"))
})
@Data
public class FieldDescriptorEntity extends BaseEntity {

    @Column(name = "field_descriptor_pattern")
    private String pattern;

    @Column(name = "field_descriptor_label")
    private String label;

    @Column(name = "field_descriptor_is_required")
    private Boolean required;

}

@Entity
@Table(name = "data_flow_steps")
@AttributeOverrides({
    @AttributeOverride(name = "id", column = @Column(name = "data_flow_step_id")),
    @AttributeOverride(name = "refId", column = @Column(name = "data_flow_step_ref_id"))
})
@DiscriminatorColumn(name = "data_flow_step_type_label", discriminatorType = DiscriminatorType.STRING)
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@Data
public class DataFlowStepEntity extends BaseEntity {

    @Column(name = "data_flow_step_name")
    private String name;

    @Column(name = "data_flow_step_description")
    private String description;

    @Column(name = "data_flow_step_ordinal")
    private Integer ordinal;

}

@Entity
@DiscriminatorValue("ADD_COLUMN")
@Data
public class AddColumnDataFlowStepEntity extends DataFlowStepEntity {

    @Column(name = "data_flow_step_field_id")
    private FieldDescriptorEntity fieldDescriptor;

}

同时使用如下SQL创建表：

CREATE TABLE IF NOT EXISTS field_descriptors (
    field_descriptor_id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    field_descriptor_ref_id VARCHAR(36) NOT NULL DEFAULT (UUID()),
    field_descriptor_pattern VARCHAR(250) NOT NULL,
    field_descriptor_label VARCHAR(100) NOT NULL,
    field_descriptor_is_required TINYINT(1) NOT NULL,

    CONSTRAINT pk_field_descriptors PRIMARY KEY (field_descriptor_id)
);

CREATE TABLE IF NOT EXISTS data_flow_steps (
    -- base fields used by all step types
    data_flow_step_id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    data_flow_step_ref_id VARCHAR(36) NOT NULL DEFAULT (UUID()),
    data_flow_step_type_label VARCHAR(100) NOT NULL,
    data_flow_step_name VARCHAR(100) NOT NULL,
    data_flow_step_description VARCHAR(250) NOT NULL,
    data_flow_step_ordinal BIGINT NOT NULL,

    -- these are the subclass fields that get reused across different types of steps
    data_flow_step_field_id BIGINT UNSIGNED,

    CONSTRAINT data_flow_steps PRIMARY KEY (data_flow_step_id),
    CONSTRAINT fk_data_flow_steps_step_field_id FOREIGN KEY (data_flow_step_field_id) REFERENCES field_descriptors (field_descriptor_id)
);

启动应用时触发Schema校验，抛出如下错误：

Caused by: org.hibernate.MappingException: Could not determine
type for: myapp.entities.FieldDescriptorEntity, at table:
data_flow_steps, for columns: [org.hibernate.mapping.Column(data_flow_step_field_id)]

错误原因 #

• @Column注解仅用于映射基本数据类型（如String、Integer、Long等）到数据库列，不能用来标注实体类类型的字段。
• AddColumnDataFlowStepEntity中的fieldDescriptor是FieldDescriptorEntity类型，属于JPA的关联关系，使用@Column会导致Hibernate无法识别该字段的映射类型，从而抛出异常。

修复方案 #

将@Column替换为关联关系注解（根据业务场景选择@ManyToOne或@OneToOne），并通过@JoinColumn指定外键列名，匹配数据库中的data_flow_step_field_id字段：

修改后的AddColumnDataFlowStepEntity代码：

@Entity
@DiscriminatorValue("ADD_COLUMN")
@Data
public class AddColumnDataFlowStepEntity extends DataFlowStepEntity {

    @ManyToOne(fetch = FetchType.LAZY) // 根据业务需求选择fetch策略，LAZY为懒加载
    @JoinColumn(name = "data_flow_step_field_id")
    private FieldDescriptorEntity fieldDescriptor;

}

补充说明 #

1. 关联关系选择：如果一个FieldDescriptorEntity可以被多个AddColumnDataFlowStepEntity引用，使用@ManyToOne；如果每个步骤仅对应唯一的字段描述符，使用@OneToOne。
2. Fetch策略：建议使用FetchType.LAZY避免全量加载关联实体，提升性能；若业务需要立即加载，可改为FetchType.EAGER。
3. 类型匹配：数据库中data_flow_step_field_id是BIGINT UNSIGNED，实体类BaseEntity的id为Long，二者类型兼容，无需额外调整。

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