Quarkus添加@SoftDelete启动报错：tableMappings为空致空指针异常

问题描述 #

在Quarkus 3.9.3项目中，仅给Shop实体添加Hibernate的@SoftDelete注解后，应用启动失败，抛出NullPointerException：

Cannot load from object array because "this.tableMappings" is null

项目原有User和Shop两个实体，运行正常；尝试过移除实体间关联列、给两个实体都添加@SoftDelete注解，问题仍未解决。

相关代码与配置 #

Shop实体代码 #

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.ManyToOne;
import org.hibernate.annotations.SoftDelete;

@Entity
@SoftDelete
public class Shop {
    @Id
    private Long id;
    private String name;
    
    @ManyToOne
    private User owner;
    
    // getter、setter省略
}

User实体代码 #

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.OneToMany;
import java.util.List;

@Entity
public class User {
    @Id
    private Long id;
    private String username;
    
    @OneToMany(mappedBy = "owner")
    private List<Shop> shops;
    
    // getter、setter省略
}

POM依赖片段 #

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-orm</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-reactive</artifactId>
</dependency>
<!-- 其他依赖省略 -->

完整报错日志 #

Caused by: java.lang.NullPointerException: Cannot load from object array because "this.tableMappings" is null
    at org.hibernate.persister.entity.AbstractEntityPersister.getTableMapping(AbstractEntityPersister.java:595)
    at org.hibernate.persister.entity.AbstractEntityPersister.getTableName(AbstractEntityPersister.java:641)
    at org.hibernate.annotations.SoftDeleteAnnotationProcessor.process(SoftDeleteAnnotationProcessor.java:52)
    at org.hibernate.annotations.SoftDeleteAnnotationProcessor.process(SoftDeleteAnnotationProcessor.java:35)
    at org.hibernate.boot.model.process.spi.MetadataBuildingProcess$1.processAnnotations(MetadataBuildingProcess.java:135)
    ... 更多栈跟踪信息

解决方案 #

1. 补充软删除字段 #

@SoftDelete默认要求实体包含一个名为deleted的布尔类型字段（映射到数据库deleted列），缺失该字段会导致元数据处理时触发NPE。修改Shop实体：

@Entity
@SoftDelete
public class Shop {
    @Id
    private Long id;
    private String name;
    private boolean deleted; // 添加默认软删除字段
    
    @ManyToOne
    private User owner;
    
    // getter、setter
}

若需自定义字段名，可通过@SoftDelete(column = "is_deleted")指定，同时实体中对应字段改为private boolean isDeleted;（遵循JPA字段与列名映射规则）。

2. 升级Quarkus版本至3.10.x+ #

Quarkus 3.9.x版本的Hibernate ORM扩展在处理@SoftDelete与实体关联时存在兼容性bug，升级到3.10.0或更高版本可直接修复该NPE问题。修改POM中Quarkus版本：

<properties>
    <quarkus.platform.version>3.10.0</quarkus.platform.version>
</properties>

3. 指定兼容的Hibernate ORM版本 #

若无法升级Quarkus，可尝试升级Hibernate ORM版本（需与Quarkus版本匹配），Quarkus 3.9.3对应默认Hibernate ORM为6.4.4.Final，可尝试升级到6.4.5.Final：

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>6.4.5.Final</version>
</dependency>

4. 临时 workaround：修改关联加载策略 #

若上述方案暂时无法实施，可将User实体中@OneToMany关联改为即时加载，避免元数据处理时的空指针：

import jakarta.persistence.FetchType;

@OneToMany(mappedBy = "owner", fetch = FetchType.EAGER)
private List<Shop> shops;

验证步骤 #

1. 按上述方案修改代码或配置
2. 执行./mvnw quarkus:dev启动应用
3. 检查启动日志，确认NPE是否消失
4. 测试软删除功能：删除Shop实体后，数据库中对应软删除字段变为true，查询时自动过滤已删除记录

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