Spring Boot 2.7.5中JpaRepository保存已存在实体触发Insert报错排查

问题分析 #

从日志对比可以看出，Spring Boot 2.7.5中Hibernate对查询出的实体执行了insert而非预期的update，导致主键重复异常。核心原因是实体状态判断逻辑在版本升级后发生了变化：原本处于detached（游离）状态的实体，被错误判定为transient（新实体），从而触发插入操作。

排查与解决步骤 #

1. 确保操作在同一事务内 #

Spring Boot 2.7默认关闭了open-in-view特性（2.6版本默认开启），这会导致查询操作结束后Session立即关闭，实体变为游离状态。如果查询和保存操作不在同一个事务中，Spring Data JPA的save方法可能无法正确识别实体已存在。

解决方法：给包含查询和保存逻辑的方法添加@Transactional注解：

import org.springframework.transaction.annotation.Transactional;
...

@Transactional
public void handleCustomer(String email) {
    Optional<Customer> customer = customerRepository.findByEmail(email);
    if (customer.isPresent()) {
        customerRepository.save(customer.get());
    } else {
        Customer custom = new Customer();
        custom.setEmail(email);
        customerRepository.save(custom);
    }
}

2. 替换save为merge操作 #

如果事务调整后问题仍存在，直接使用JPA的merge方法显式更新实体，避免Spring Data JPA的状态判断逻辑干扰：

import javax.persistence.EntityManager;
import org.springframework.beans.factory.annotation.Autowired;
...

@Autowired
private EntityManager entityManager;

public void handleCustomer(String email) {
    Optional<Customer> customer = customerRepository.findByEmail(email);
    if (customer.isPresent()) {
        entityManager.merge(customer.get());
    } else {
        Customer custom = new Customer();
        custom.setEmail(email);
        customerRepository.save(custom);
    }
}

也可以在Repository接口中自定义merge方法：

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;

public interface CustomerRepository extends JpaRepository<Customer, String> {
    Optional<Customer> findByEmail(String email);

    @Modifying
    @Query("update Customer c set c = ?1 where c.email = ?1.email")
    void merge(Customer customer);
}

3. 验证实体主键配置 #

确认Customer实体的主键注解正确，避免主键生成策略导致的状态误判：

import javax.persistence.Id;
import javax.persistence.Entity;

@Entity
public class Customer {
    @Id // 确保email被正确标记为主键
    private String email;
    // 其他字段和getter/setter
}

如果主键是手动赋值（如本例的email），确保查询出的实体主键值未被意外修改或为空。

4. 检查Hibernate实体状态 #

在保存前可以打印实体状态，确认Hibernate对实体的判定：

import org.hibernate.Session;
import javax.persistence.EntityManager;
...

Session session = entityManager.unwrap(Session.class);
if (session.contains(customer.get())) {
    System.out.println("实体处于持久化状态");
} else {
    System.out.println("实体处于游离状态");
}

如果输出为"实体处于游离状态"，说明当前Session不包含该实体，此时使用merge是更可靠的选择。

临时验证方案（不推荐长期使用） #

若怀疑是open-in-view关闭导致的问题，可以临时在application.properties中开启该特性验证：

spring.jpa.open-in-view=true

注意：该特性可能导致Session长期持有，引发性能问题，仅用于验证，不建议生产环境开启。

内容的提问来源于stack exchange，提问作者ayoub.ontwerper