Quarkus自定义扩展实体持久化报错：'Not an entity'问题求助

问题分析 #

你遇到的Not an entity错误，核心原因是Quarkus的JPA引擎未将ConfigurationEntity识别为实体类。仅通过AdditionalBeanBuildItem注册Bean只能确保其被CDI容器管理，无法告知Quarkus这是需要JPA处理的实体。

解决方案 #

1. 用JpaEntityBuildItem注册实体 #

在扩展的构建步骤中，补充JpaEntityBuildItem明确标记目标类为JPA实体：

import io.quarkus.hibernate.orm.deployment.JpaEntityBuildItem;

@BuildStep
void registerConfigurationEntity(BuildProducer<JpaEntityBuildItem> entityProducer,
                                 BuildProducer<AdditionalBeanBuildItem> beanProducer) {
    // 注册为JPA实体
    entityProducer.produce(JpaEntityBuildItem.of(ConfigurationEntity.class));
    // 确保Bean不被移除（按需添加）
    beanProducer.produce(AdditionalBeanBuildItem.unremovableOf(ConfigurationEntity.class));
}

2. 生成Jandex索引 #

Quarkus依赖Jandex索引发现注解类，在扩展的pom.xml中添加插件生成索引：

<build>
    <plugins>
        <plugin>
            <groupId>org.jboss.jandex</groupId>
            <artifactId>jandex-maven-plugin</artifactId>
            <version>3.1.1</version>
            <executions>
                <execution>
                    <id>make-index</id>
                    <goals>
                        <goal>jandex</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

如果BaseEntity带有@MappedSuperclass注解，需确保该类也被包含在索引中。

3. 检查扩展依赖配置 #

在扩展项目中正确引入Hibernate ORM依赖，scope设为provided（主应用会提供运行时依赖）：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-orm</artifactId>
    <scope>provided</scope>
</dependency>

4. 验证父类注解正确性 #

确认BaseEntity的@MappedSuperclass注解导入正确（根据Quarkus版本选择javax.persistence或jakarta.persistence包），且该类被正确索引。

验证步骤 #

1. 清理并重新构建扩展：mvn clean install
2. 更新主应用的扩展依赖，执行mvn quarkus:dev重启应用
3. 再次尝试持久化操作，确认错误是否消失

内容的提问来源于stack exchange，提问作者Çağrı BIYIK