非主键自动生成UUID的PostgreSQL表JPA保存失败问题排查

问题场景 #

现有预定义PostgreSQL表，非主键UUID类型列配置默认自动生成值，DDL如下：

CREATE SEQUENCE IF NOT EXISTS uuid_column_table_seq;
CREATE TABLE IF NOT EXISTS uuid_column_table
(
    uuid_column_table_id     integer  DEFAULT nextval('uuid_column_table_seq') NOT NULL,
    not_pk_uuid              uuid     DEFAULT uuid_generate_v4()               NOT NULL,
    label                    text,
    PRIMARY KEY (uuid_column_table_id)
);

对应JPA实体定义如下：

@Entity
@Table(name = "uuid_column_table")
public class UuidColumnTableEntity {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Integer uuidColumnTableId;

  @Column
  @GeneratedValue
  private UUID notPkUuid;

  @Column
  private String label;

  // getter和setter方法
  public Integer getUuidColumnTableId() {
    return this.uuidColumnTableId;
  }

  public void setUuidColumnTableId(Integer uuidColumnTableId) {
    this.uuidColumnTableId = uuidColumnTableId;
  }

  public UUID getNotPkUuid() {
    return this.notPkUuid;
  }

  public void setNotPkUuid(UUID notPkUuid) {
    this.notPkUuid = notPkUuid;
  }

  public String getLabel() {
    return this.label;
  }

  public void setLabel(String label) {
    this.label = label;
  }
}

执行以下代码调用JPA Repository的save()方法时：

var uuidColumnTableEntity = new UuidColumnTableEntity();
uuidColumnTableEntity.setLabel("Test Label");
var uuidColumnTableEntityWithPk = UuidColumnTableEntityRepository.save(uuidColumnTableEntity);

触发约束异常：

could not execute statement; SQL [n/a]; constraint [not_pk_uuid" of relation "uuid_column_table]; nested exception is org.hibernate.exception.ConstraintViolationException: could not execute statement

要求在无法修改PostgreSQL DDL的前提下，修正JPA实体定义解决该问题。使用版本：Java 17、Spring Boot 2.5.6、Jakarta Persistence 2.2.3、PostgreSQL 13.3

问题原因 #

原实体中@GeneratedValue未指定合适的生成策略，Hibernate会尝试自行处理not_pk_uuid字段的值，但最终在INSERT语句中传递了null值。而数据库的默认值仅当INSERT语句不包含该列时才会生效，因此触发非空约束异常。

修正方案 #

修改not_pk_uuid字段的注解，让Hibernate在插入时不主动传递该列，同时告知Hibernate该字段值由数据库生成，插入后将值回写到实体中。

修正后的完整JPA实体代码：

import org.hibernate.annotations.GenericGenerator;
import javax.persistence.*;
import java.util.UUID;

@Entity
@Table(name = "uuid_column_table")
public class UuidColumnTableEntity {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Integer uuidColumnTableId;

  @Column(name = "not_pk_uuid", insertable = false, updatable = false)
  @GeneratedValue(generator = "uuid2")
  @GenericGenerator(name = "uuid2", strategy = "uuid2")
  private UUID notPkUuid;

  @Column
  private String label;

  // getter和setter方法保持不变
  public Integer getUuidColumnTableId() {
    return this.uuidColumnTableId;
  }

  public void setUuidColumnTableId(Integer uuidColumnTableId) {
    this.uuidColumnTableId = uuidColumnTableId;
  }

  public UUID getNotPkUuid() {
    return this.notPkUuid;
  }

  public void setNotPkUuid(UUID notPkUuid) {
    this.notPkUuid = notPkUuid;
  }

  public String getLabel() {
    return this.label;
  }

  public void setLabel(String label) {
    this.label = label;
  }
}

关键修改说明 #

• @Column(insertable = false, updatable = false)：指定该列在INSERT和UPDATE语句中不被包含，让数据库使用预定义的默认值生成UUID；updatable = false可根据业务需求调整，若允许更新该列可移除该属性。
• @GeneratedValue(generator = "uuid2") + @GenericGenerator(name = "uuid2", strategy = "uuid2")：指定Hibernate使用UUID生成器，确保插入操作完成后，能将数据库生成的UUID值回写到实体对象中。

验证效果 #

修改后执行save()方法，Hibernate生成的INSERT语句将不再包含not_pk_uuid列，数据库自动生成UUID值，同时实体对象的notPkUuid字段会被正确赋值，不会触发非空约束异常。

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