Hibernate多对多关联含额外字段添加时触发NonUniqueObjectException

在SpringBoot 3.2.4 + Hibernate + Java17环境下，维护用户与团队的多对多关联（带额外字段）时，执行更新操作抛出NonUniqueObjectException，错误提示会话中已存在相同标识符的不同对象实例。

问题根源 #

1. UserTeamEntity缺少无参构造函数：Hibernate在实例化实体（尤其是EAGER加载场景）时依赖无参构造函数，反射创建实例时可能生成重复对象。
2. 嵌入式ID类未实现相等性判断：UserTeamId作为关联实体的唯一标识，未重写equals()和hashCode()，导致Hibernate无法识别相同ID的对象。
3. 关联实体未实现相等性判断：UserTeamEntity未基于ID重写equals()和hashCode()，集合无法正确判断对象唯一性，引发重复实例问题。
4. 业务方法参数顺序错误：TeamEntity的addUser()方法中，创建UserTeamEntity时参数传递颠倒，虽不直接触发当前异常，但会导致业务逻辑错误。

解决方案 #

1. 为UserTeamId实现equals()和hashCode() #

嵌入式ID必须基于属性实现相等性判断：

public class UserTeamId implements Serializable {
    private String userLoginName;
    private Long teamId;

    // 无参构造函数
    public UserTeamId() {}

    public UserTeamId(String userLoginName, Long teamId) {
        this.userLoginName = userLoginName;
        this.teamId = teamId;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        UserTeamId that = (UserTeamId) o;
        return Objects.equals(userLoginName, that.userLoginName) && Objects.equals(teamId, that.teamId);
    }

    @Override
    public int hashCode() {
        return Objects.hash(userLoginName, teamId);
    }
}

2. 为UserTeamEntity添加无参构造函数并实现相等性判断 #

补充Hibernate所需的无参构造函数，基于ID实现实体相等性：

public class UserTeamEntity {

    @EmbeddedId
    private UserTeamId id;

    @ManyToOne(fetch = FetchType.EAGER)
    @MapsId("userLoginName")
    private UserEntity user;

    @ManyToOne(fetch = FetchType.EAGER)
    @MapsId("teamId")
    private TeamEntity team;

    @Column(name = "is_team_leader")
    @Convert(converter = YesNoConverter.class)
    private boolean isTeamLeader = false;

    @Column(name = "is_user_primary_team")
    @Convert(converter = YesNoConverter.class)
    private boolean isUserPrimaryTeam = false;

    // 添加无参构造函数（Hibernate要求）
    protected UserTeamEntity() {}

    public UserTeamEntity(UserEntity user, TeamEntity team, boolean isTeamLeader, boolean isUserPrimaryTeam) {
        this.id = new UserTeamId(user.getLoginName(), team.getId());
        this.user = user;
        this.team = team;
        this.isTeamLeader = isTeamLeader;
        this.isUserPrimaryTeam = isUserPrimaryTeam;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        UserTeamEntity that = (UserTeamEntity) o;
        return Objects.equals(id, that.id);
    }

    @Override
    public int hashCode() {
        return Objects.hash(id);
    }

    // 补充getter/setter
    public boolean isTeamLeader() {
        return isTeamLeader;
    }

    public void setTeamLeader(boolean teamLeader) {
        isTeamLeader = teamLeader;
    }

    public boolean isUserPrimaryTeam() {
        return isUserPrimaryTeam;
    }

    public void setUserPrimaryTeam(boolean userPrimaryTeam) {
        isUserPrimaryTeam = userPrimaryTeam;
    }

    public UserEntity getUser() {
        return user;
    }
}

3. 修正TeamEntity的addUser()方法参数顺序 #

确保创建关联实体时参数传递正确：

public void addUser(UserEntity userEntity, boolean isPrimaryTeam, boolean isLeader) {
    Optional<UserTeamEntity> optionalUserTeam = users.stream()
            .filter(userTeamEntity -> userTeamEntity.getUser().equals(userEntity))
            .findFirst();

    if (optionalUserTeam.isPresent()) {
        optionalUserTeam.get().setTeamLeader(isLeader);
        optionalUserTeam.get().setUserPrimaryTeam(isPrimaryTeam);
    } else {
        // 修正参数顺序：isLeader对应isTeamLeader，isPrimaryTeam对应isUserPrimaryTeam
        UserTeamEntity userTeamEntity = new UserTeamEntity(userEntity, this, isLeader, isPrimaryTeam);
        users.add(userTeamEntity);
        userEntity.getUserTeams().add(userTeamEntity);
    }
}

4. 确保会话实体一致性 #

业务代码中避免重复加载相同实体生成游离对象：

• 如果updateTeam()方法使用merge()，需使用返回的托管对象进行后续操作；
• 若操作的是findById()返回的托管对象，无需手动调用merge()，事务提交时Hibernate会自动同步数据。

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