Hibernate OneToMany关联值在多线程操作中无法删除的问题排查

问题 #

我有两个@Entity实体类：Document（包含PDF的1到多个页面）和Tag（为Document添加上下文或描述，例如美国银行对账单文档可标记BOA、STATEMENT）。Document实体通过如下方式持有Tag：

@Entity(name="document")
public class Document extends TagBearing {

...

@MappedSuperclass
public abstract class TagBearing extends LobMappedEntity {
    
    @OneToMany(fetch = FetchType.EAGER, cascade = CascadeType.ALL)
    protected Set<Tag> tags = new TreeSet<>();

我的Spring Boot Web应用使用Vaadin、JPA Repositories和Hibernate。手动为Document添加或移除Tag时，生成的document_tags表记录会正常增减。但我有一个无头运行的独立应用，用于执行文档的OCR等耗时任务，该应用除Vaadin外依赖与Web应用一致。

当该无头应用以多线程方式运行时，通过JpaRepository命名查询加载文档、调整Tag后调用saveAndFlush：添加新Tag（未在Set中存在）正常，但清空Set后保存无法删除document_tags表中的记录；尝试添加已存在的Tag还会抛出异常：

2024-04-01 20:51:39.466 [Thread-7] ERROR o.h.e.jdbc.spi.SqlExceptionHelper - Duplicate entry '781-427' for key 'document_tags.PRIMARY'

推测Hibernate/JPA的管理机制未正确传入工作线程，导致清空Tag后级联删除未触发，请问如何解决？还有哪些原因会导致@OneToMany关联记录无法删除？

解决方案与排查方向 #

一、多线程场景下的核心问题修复 #

1. 保证每个线程使用独立的EntityManager
   JPA的EntityManager并非线程安全，多线程共享实例会导致持久化上下文混乱，关联变更无法被正确追踪：

   • 基于EntityManagerFactory为每个工作线程创建独立的EntityManager实例，操作完成后主动关闭。
   • 如果依赖Spring事务，需确保每个线程的任务逻辑处于独立事务中：将任务封装到Spring管理的Bean中，在方法上添加@Transactional注解（手动创建的线程无法自动继承父线程事务上下文，必须显式声明）。

2. 显式触发持久化上下文的状态同步
   多线程下Hibernate可能无法自动检测集合变更，可在保存前显式合并实体状态：

   document.getTags().clear();
   entityManager.merge(document);
   entityManager.flush();
   

3. 解决重复键异常
   添加已存在Tag时的重复键错误，源于Tag的身份判断或持久化上下文冲突：

   • 检查Tag类的equals和hashCode实现，必须基于业务主键（如id）编写，避免TreeSet误判为新元素重复添加。
   • 加载Tag时优先从当前线程的EntityManager中获取（用entityManager.find(Tag.class, tagId)），而非创建新实例，避免Hibernate将现有Tag识别为新实体尝试插入。

二、@OneToMany关联记录无法删除的其他常见原因 #

• 缺失关联维护端配置
  当前@OneToMany未指定mappedBy，若Tag实体无对应的@ManyToOne关联，Hibernate无法正确处理中间表的删除逻辑。需补充双向关联配置：

  // Tag实体中添加
  @ManyToOne
  @JoinColumn(name = "document_id")
  private Document document;
  

  同时在@OneToMany中声明mappedBy = "document"，明确关联维护端。

• CascadeType或关联引用限制
  即使配置了CascadeType.ALL，若Tag被其他实体引用，级联删除会被阻断；双向关联时需确保两端的级联规则匹配。

• FetchType.EAGER的线程干扰
  FetchType.EAGER会在加载Document时立即初始化tags集合，多线程并发修改同一Document时，易导致集合状态不一致。可改为FetchType.LAZY，在事务内手动初始化集合。

• 事务边界错误
  若修改操作未在有效事务内执行，或事务因异常回滚，saveAndFlush的变更无法持久化到数据库。需确保所有实体修改操作都包裹在事务中。

• 一级缓存（Session缓存）不一致
  多线程共享Session时，缓存中的实体状态可能与数据库脱节，导致修改不生效。必须保证每个线程使用独立的Session/EntityManager。

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