Spring JPA复合主键插入失败，仅更新正常问题求助

核心问题根源 #

你遇到的插入失败、JPA执行merge而非insert的情况，主要由以下几个错误导致：

1. 复合主键类（UserIdEntity）中错误添加了JPA注解
2. 自增主键字段userId使用了@NotNull注解，导致插入前验证失败
3. JPA无法正确识别新实体状态，误判为已存在的detached实体

修复步骤 #

1. 修正复合主键类UserIdEntity

主键类仅需作为Serializable的属性载体，不需要任何JPA注解（如@Column、@NotNull），删除多余注解：

@NoArgsConstructor
@AllArgsConstructor
@Data
public class UserIdEntity implements Serializable {
    private BigInteger userId;
    private String userNum;
    private String userCd;
}

2. 调整UserEntity的注解配置

• 移除userId上的@NotNull，改用@Column(nullable = false)（避免插入前主键未生成时触发验证错误）
• 确保主键字段的注解仅在实体类中定义：

@Entity
@Table(name = "USERS", schema = "UR")
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
@IdClass(UserIdEntity.class)
public class UserEntity {
    @SequenceGenerator(
            name = "sequence_name",
            sequenceName = "SEQ_USER_ID",
            allocationSize = 1,
            schema = "AR")
    @GeneratedValue(generator = "sequence_name")
    @Id
    @Column(name = "USER_ID", length = 8, unique = true, columnDefinition = "BIGINT", nullable = false)
    private BigInteger userId;

    @Id
    @Column(name = "USER_NUM", nullable = false)
    private String userNum;

    @Id
    @Column(name = "USER_CD", nullable = false)
    private String userCd;

    @Column(name = "USER_ADDR", nullable = false)
    private String userAddr;
}

3. 正确构造插入实体

插入时确保userId为null，让JPA明确识别这是新实体，触发insert而非merge：

// 构造新用户，userId留空由序列生成
UserEntity newUser = UserEntity.builder()
        .userNum("你的默认userNum")
        .userCd("你的默认userCd")
        .userAddr("用户地址")
        .build();
userRepository.save(newUser);

关键逻辑说明 #

• JPA通过主键字段是否非空判断实体状态：若复合主键中所有字段都有值，JPA会认为实体已存在，执行merge；若生成型主键（如userId）为null，且配置正确，JPA会识别为新实体，执行insert并自动生成主键值。
• 主键类中的JPA注解会干扰JPA对主键的判断逻辑，必须移除。

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