Spring Data中如何仅保存唯一模型？解决唯一键冲突异常

问题原因 #

你遇到的org.postgresql.util.PSQLException: ERROR: duplicate key value violates unique constraint异常，本质是要保存的模型违反了数据库中已定义的唯一约束（非主键字段的唯一索引）。Spring Data的save()方法仅会根据主键判断是插入还是更新，若唯一约束字段重复（主键未重复），就会触发这个数据库层面的错误。

解决方案 #

1. 提前查询，按需插入/更新 #

这是最通用的方案，先通过唯一字段查询是否存在对应记录，存在则更新，不存在则插入：

// 假设实体类User有唯一字段email
Optional<User> existingUser = userRepository.findByEmail(user.getEmail());
if (existingUser.isPresent()) {
    // 更新现有记录的需要修改的字段
    User updatedUser = existingUser.get();
    updatedUser.setName(user.getName());
    updatedUser.setPhone(user.getPhone());
    userRepository.save(updatedUser);
} else {
    // 插入新记录
    userRepository.save(user);
}

注意：高并发场景下这种方式可能存在竞态条件，需配合数据库锁或乐观锁优化。

2. 使用PostgreSQL原生UPSERT（推荐高并发场景） #

利用PostgreSQL的ON CONFLICT语法实现原子性的插入/更新（UPSERT），避免竞态条件。在Repository中自定义方法：

@Repository
public interface UserRepository extends JpaRepository<User, Long> {

    @Modifying
    @Transactional
    @Query(value = "INSERT INTO users (email, name, phone) VALUES (:email, :name, :phone) " +
                   "ON CONFLICT (email) DO UPDATE SET name = :name, phone = :phone", 
           nativeQuery = true)
    void upsertUser(@Param("email") String email, 
                    @Param("name") String name, 
                    @Param("phone") String phone);
}

调用该方法时，数据库会自动判断：若email不存在则插入，存在则更新指定字段，全程原子操作，不会触发唯一约束异常。

3. 捕获异常兜底（不推荐） #

如果无法提前判断或需要兼容旧代码，可以捕获DataIntegrityViolationException（Spring对数据库约束异常的封装）做兜底处理：

try {
    userRepository.save(user);
} catch (DataIntegrityViolationException e) {
    // 检查异常根源是否为唯一约束冲突
    if (e.getRootCause() instanceof PSQLException && 
        ((PSQLException) e.getRootCause()).getSQLState().equals("23505")) {
        // 抛出业务异常或返回提示信息
        throw new RuntimeException("该记录已存在");
    }
    // 其他约束异常则重新抛出
    throw e;
}

这种方式属于事后处理，不如前两种优雅，仅作为临时解决方案。

4. 实体类层面强化约束（辅助） #

在实体类的唯一字段上添加@Column(unique = true)，确保Hibernate生成表结构时自动创建唯一约束（手动建表则需自行添加唯一索引）：

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(unique = true, nullable = false)
    private String email; // 唯一字段

    private String name;
    private String phone;

    // getter、setter方法
}

内容的提问来源于stack exchange，提问作者Вадим Липаков