Spring Boot中JPA @JoinTable复合主键配置问题

在Spring Boot应用中使用Spring Data JPA、Hibernate和H2数据库时，定义了如下User实体：

@Data
@Entity
@Table(name = "users")
public class User {

    @Id
    @Column(nullable = false, name = "username", length = 100)
    private String username;

    @JoinTable(name = "userrole", 
        joinColumns = { @JoinColumn(name = "username") },
        inverseJoinColumns = { @JoinColumn(name = "role") }
    )
    @OneToMany(
        cascade = CascadeType.ALL, 
        orphanRemoval = true
    )
    private List<Role> roles;
}

遇到的问题：自动生成的关联表userrole仅将username作为单一主键，插入同一username对应不同role的记录时，会因主键重复抛出异常。尝试调整@JoinColumns的多种配置均无效，部分配置甚至导致表创建失败。

使用@OneToMany搭配@JoinTable时，Hibernate默认会将主表（users）的主键作为关联表（userrole）的唯一主键。这种映射逻辑仅适用于一个主表实体对应最多一个关联实体的场景，无法支持同一用户对应多个角色的需求，因为重复的username会触发主键冲突。

方案1：创建独立的UserRole关联实体 #

通过显式定义关联表对应的实体类，手动指定复合主键，从而灵活控制关联表结构：

1. 创建UserRole实体，使用username和role作为复合主键
2. 在User实体中建立与UserRole的@OneToMany关联
3. 在Role实体中建立与UserRole的@ManyToOne关联（根据业务需求调整）

示例代码：

// 复合主键类
@Embeddable
public class UserRoleId implements Serializable {
    @Column(name = "username")
    private String username;
    @Column(name = "role")
    private String role;
    // 需重写equals和hashCode方法
}

// UserRole实体
@Entity
@Table(name = "userrole")
public class UserRole {
    @EmbeddedId
    private UserRoleId id;

    @ManyToOne
    @MapsId("username")
    @JoinColumn(name = "username")
    private User user;

    @ManyToOne
    @MapsId("role")
    @JoinColumn(name = "role")
    private Role role;
    // getter、setter方法
}

// 修改后的User实体
@Data
@Entity
@Table(name = "users")
public class User {
    @Id
    @Column(nullable = false, name = "username", length = 100)
    private String username;

    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<UserRole> userRoles;
}

该方案能完全掌控关联表的结构和映射关系，适合需要在关联表中添加额外字段（如创建时间、权限等级）的场景。

方案2：改用@ManyToMany关联 #

如果User和Role之间是标准的多对多关系（一个用户可拥有多个角色，一个角色可被多个用户拥有），直接将@OneToMany替换为@ManyToMany即可，原@JoinTable配置会自动生成包含username和role的复合主键关联表：

修改后的User实体代码：

@Data
@Entity
@Table(name = "users")
public class User {

    @Id
    @Column(nullable = false, name = "username", length = 100)
    private String username;

    @JoinTable(name = "userrole", 
        joinColumns = { @JoinColumn(name = "username") },
        inverseJoinColumns = { @JoinColumn(name = "role") }
    )
    @ManyToMany(
        cascade = CascadeType.ALL
    )
    private List<Role> roles;
}

此方案更简洁，无需额外创建关联实体，适合无额外字段需求的标准多对多场景。

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