Spring Data JPA中关联游离实体时的级联持久化异常如何解决？

问题场景 #

在用户注册流程中，新用户需要关联默认的USER角色。首次注册时角色不存在，新用户和角色可正常持久化；但第二次注册时，关联已存在的角色会抛出异常：

Caused by: org.hibernate.PersistentObjectException: detached entity passed to persist: com.example.tokenservice.data.entity.Role

核心代码如下：

注册请求处理 #

public Mono<ServerResponse> signUp(ServerRequest request) {
    return request.bodyToMono(UserDto.class)
            .map(userMapper::toUser)
            .map(userService::encodePassword)
            .map(userService::addDefaultRoles)
            .map(userService::save)
            .map(this::toAuthenticatedUpat)
            .map(tokenService::generateTokenFor)
            .transform(jwt -> ServerResponse.status(HttpStatus.CREATED).body(jwt, String.class));
}

UserService关键方法 #

@Override
public User save(User user) {
    return userRepository.save(user); // Spring Data JPA Repository
}

@Override
@Transactional // 仅该方法标注事务
public User addDefaultRoles(User user) {
    Optional<Role> userRoleOptional = roleService.findByAuthority(Role.USER);
    Role userRole = userRoleOptional.orElse(new Role(Role.USER));
    userRole.addUser(user);
    user.addRole(userRole);
    return user;
}

实体关联配置 #

// User实体
public class User implements UserDetails {
    // ...
    @ManyToMany(cascade = CascadeType.PERSIST) // 级联持久化配置
    @JoinTable(name = "users_roles",
            joinColumns = @JoinColumn(name = "user_id"),
            inverseJoinColumns = @JoinColumn(name = "role_id"))
    private Set<Role> authorities;
}

// Role实体
public class Role implements GrantedAuthority {
    public static final String USER = "user";
    // ...
    @ManyToMany(mappedBy = "authorities")
    private Set<User> users;
}

异常原因 #

第二次注册时，addDefaultRoles方法中查询到的Role实体在事务结束后脱离了EntityManager的持久化上下文，成为游离状态。后续调用userRepository.save(user)时，Spring Data JPA判断User是新实体，执行entityManager.persist(user)，并通过CascadeType.PERSIST级联尝试持久化关联的Role。但Hibernate禁止对游离实体执行persist操作，因此抛出异常。

解决方案 #

方案1：统一事务范围，确保Role处于持久化上下文 #

将用户创建、角色关联、保存的逻辑放在同一个事务中，避免Role变为游离状态。修改UserServiceImpl，新增一个包含完整逻辑的事务方法：

@Override
@Transactional
public User createUserWithDefaultRoles(User user) {
    user = encodePassword(user);
    Optional<Role> userRoleOptional = roleService.findByAuthority(Role.USER);
    Role userRole = userRoleOptional.orElse(new Role(Role.USER));
    userRole.addUser(user);
    user.addRole(userRole);
    return userRepository.save(user);
}

然后更新注册方法的调用：

public Mono<ServerResponse> signUp(ServerRequest request) {
    return request.bodyToMono(UserDto.class)
            .map(userMapper::toUser)
            .map(userService::createUserWithDefaultRoles)
            .map(this::toAuthenticatedUpat)
            .map(tokenService::generateTokenFor)
            .transform(jwt -> ServerResponse.status(HttpStatus.CREATED).body(jwt, String.class));
}

整个流程在同一个事务内，查询到的Role始终处于持久化上下文，级联persist会自动识别已存在的实体，不会触发错误。

方案2：调整级联策略或单独处理Role持久化 #

如果不需要通过User级联创建Role（比如Role是预先初始化的基础数据），可以调整级联类型：

@ManyToMany(cascade = CascadeType.MERGE) // 仅级联合并，而非持久化
@JoinTable(name = "users_roles",
        joinColumns = @JoinColumn(name = "user_id"),
        inverseJoinColumns = @JoinColumn(name = "role_id"))
private Set<Role> authorities;

若仍需支持首次注册时自动创建Role，则在addDefaultRoles中单独保存新Role：

@Override
@Transactional
public User addDefaultRoles(User user) {
    Optional<Role> userRoleOptional = roleService.findByAuthority(Role.USER);
    Role userRole;
    if (userRoleOptional.isPresent()) {
        userRole = userRoleOptional.get();
    } else {
        userRole = new Role(Role.USER);
        userRole = roleService.save(userRole); // 先保存Role，使其进入持久化上下文
    }
    userRole.addUser(user);
    user.addRole(userRole);
    return user;
}

方案3：使用merge替代persist保存User #

手动使用entityManager.merge()处理用户保存，merge会自动处理关联的游离实体：

@Autowired
private EntityManager entityManager;

@Override
public User save(User user) {
    return entityManager.merge(user);
}

merge操作会将游离状态的Role合并到持久化上下文，同时持久化新的User，避免异常。

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