Quarkus 3 + Hibernate 6关联报错：未知实体com.step.common.model.Company

问题分析 #

升级到Quarkus 3后出现Association 'com.step.trackactions.model.PlatformActionLeadEntity.company' targets an unknown entity named 'com.step.common.model.Company'错误，核心原因有两点：

1. 外部依赖中的Company和Customer类同时标注了@Entity和@MappedSuperclass，这两个注解存在冲突——@MappedSuperclass用于定义可被继承的映射元数据，本身不会被当作实体类识别，与@Entity的实体定义作用矛盾。
2. Quarkus 3对Hibernate ORM的包扫描逻辑做了调整，旧版的quarkus.hibernate-orm.packages=com.step配置无法正确扫描到外部依赖中的实体类。

解决方案 #

1. 修正实体类注解冲突 #

移除Company和Customer类上的@MappedSuperclass注解，仅保留@Entity：

@Entity
@Table(name = "Company")
@RegisterForReflection
public class Company extends PanacheEntityBase implements Cloneable { ... }

@Entity
@Table(name = "Customer")
@RegisterForReflection
public class Customer extends PanacheEntityBase implements Cloneable { ... }

2. 调整Quarkus 3的实体扫描配置 #

在application.properties中替换或补充配置，确保覆盖外部依赖的实体包路径：

# 明确指定所有包含实体的包，包括项目内部和外部依赖的包
quarkus.hibernate-orm.packages-to-scan=com.step.trackactions.model,com.step.common.model

如果希望保留根路径扫描，可添加额外配置强制扫描依赖中的包：

quarkus.hibernate-orm.packages=com.step
# 允许扫描外部依赖中的指定包路径
quarkus.hibernate-orm.scan-in-flyway-locations=true

3. 补充实体关联注解（建议操作） #

在PlatformActionLeadEntity的关联字段上添加对应关系注解（根据实际业务调整，示例为多对一关系），避免后续映射异常：

@Entity
@Table(name = "PlatformAction")
@RegisterForReflection
public class PlatformActionLeadEntity{

    @ManyToOne
    private Customer customer;

    @ManyToOne
    private Company company;

}

内容的提问来源于stack exchange，提问作者Lorenzo De Francesco