Hibernate 懒加载陷阱:Lombok @Data 导致用户角色丢失的深度分析

问题起因#

在一个基于 Spring Boot 3.4.1 + Spring Security 的用户系统中,遇到了一个诡异的 Bug:用户登录成功,JWT Token 正常签发,但权限验证却全部失败。

症状表现#

1
// 日志输出
2
=== DEBUG: User loaded ===
3
Username: admin
4
Roles count: 0           // ❌ 期望值应该是 1
5
========================

更奇怪的是,第一条 SQL 查询明明成功 JOIN 了 sys_role 表,却在业务逻辑中丢失了角色数据。

问题排查过程#

第一步:检查 SQL 日志#

启用 Hibernate SQL 日志后,发现了异常的查询序列:

1
-- ✅ 第一条查询 (正确)
2
SELECT DISTINCT u.*, r.*
3
FROM sys_user u
4
LEFT JOIN sys_user_role ur ON u.id = ur.user_id
5
LEFT JOIN sys_role r ON r.id = ur.role_id
6
WHERE u.username = ?
7

8
-- ⚠️ 后续触发的额外查询
9
SELECT p.* FROM sys_role_permission rp
10
JOIN sys_permission p ON p.id = rp.permission_id
11
WHERE rp.role_id = ?
12

13
SELECT u.* FROM sys_user_role ur
14
JOIN sys_user u ON u.id = ur.user_id
15
WHERE ur.role_id = ?
16

17
SELECT r.* FROM sys_user_role ur
18
JOIN sys_role r ON r.id = ur.role_id
19
WHERE ur.user_id = ?

关键发现: 后续的 3-4 条 SQL 查询是意外触发的懒加载!

第二步:定位触发点#

通过调试,发现触发点在调试日志中:

1
@Override
2
@Transactional
3
public UserDetails loadUserByUsername(String username) {
4
    User user = userRepository.findByUsernameWithRoles(username)
5
        .orElseThrow(() -> new UsernameNotFoundException("..."));
6

7
    // 🔴 触发点:这行日志
8
    user.getRoles().forEach(role -> {
9
        System.out.println("  Role: " + role.getCode() + " (" + role.getName() + ")");
10
    });
11

12
    return UserDetailsImpl.build(user);
13
}

问题: 为什么访问 role.getCode() 会触发额外的 SQL 查询?

第三步:找到罪魁祸首#

检查 Role 实体类,发现了问题所在:

1
@Data  // 🔴 问题根源!
2
@Entity
3
@Table(name = "sys_role")
4
public class Role {
5
    // ...
6

7
    @ManyToMany(fetch = FetchType.LAZY)
8
    private Set<Permission> permissions = new HashSet<>();
9

10
    @ManyToMany(mappedBy = "roles", fetch = FetchType.LAZY)
11
    private Set<User> users = new HashSet<>();
12
}

关键洞察:

Lombok @Data 注解自动生成的 toString() 方法会访问所有字段,包括懒加载的 permissions 和 users:

1
// Lombok 自动生成的代码
2
@Override
3
public String toString() {
4
    return "Role{" +
5
        "id=" + id +
6
        ", name=" + name +
7
        ", permissions=" + permissions +  // 🔴 触发懒加载!
8
        ", users=" + users +               // 🔴 触发循环引用!
9
        "}";
10
}

当调试日志中隐式调用 role.toString() 时,就会触发这些懒加载字段的查询,导致 Hibernate Session 状态混乱,最终角色集合丢失!

问题本质#

这是一个典型的 Lombok 便利性 vs JPA 懒加载的冲突:

触发链路#

1
1. 调用 userRepository.findByUsernameWithRoles()
2
   ↓ ✅ SQL 正确查询,roles 集合已加载
3

4
2. 调试日志访问 role 对象
5
   ↓ 🔴 隐式调用 role.toString()
6

7
3. Lombok @Data 生成的 toString() 访问 permissions
8
   ↓ 🔴 触发 Hibernate 懒加载查询
9

10
4. toString() 访问 users (双向引用)
11
   ↓ 🔴 触发循环查询 User → Role → User...
12

13
5. Hibernate Session 状态混乱
14
   ↓ ❌ roles 集合被清空
15

16
6. UserDetailsImpl.build(user) 获取空角色列表
17
   ↓ ❌ 权限验证失败

性能影响#

指标	修复前	修复后
SQL 查询次数	5-6 条	1 条
响应时间	50-100ms	10-20ms
角色数据	❌ 丢失	✅ 正常

解决方案#

核心策略#

移除 Lombok @Data,手动实现 toString/equals/hashCode,仅访问基础字段

修复代码#

1. Role 实体类#

1
@Getter  // ✅ 替换 @Data
2
@Setter
3
@Entity
4
@Table(name = "sys_role")
5
public class Role {
6
    @Id
7
    @GeneratedValue(strategy = GenerationType.IDENTITY)
8
    private Long id;
9

10
    @Column(nullable = false)
11
    private String name;
12

13
    @Column(unique = true, nullable = false, length = 50)
14
    private String code;
15

16
    @ManyToMany(fetch = FetchType.LAZY)
17
    private Set<Permission> permissions = new HashSet<>();
18

19
    @ManyToMany(mappedBy = "roles", fetch = FetchType.LAZY)
20
    private Set<User> users = new HashSet<>();
21

22
    // ✅ 自定义 toString(),仅输出基础字段
23
    @Override
24
    public String toString() {
25
        return "Role{id=" + id + ", code=" + code + ", name=" + name + "}";
26
    }
27

28
    // ✅ equals/hashCode 仅使用 ID
29
    @Override
30
    public boolean equals(Object o) {
31
        if (this == o) return true;
32
        if (!(o instanceof Role)) return false;
33
        Role role = (Role) o;
34
        return id != null && id.equals(role.id);
35
    }
36

37
    @Override
38
    public int hashCode() {
39
        return getClass().hashCode();
40
    }
41
}

2. User 实体类#

1
@Getter
2
@Setter
3
@Entity
4
@Table(name = "sys_user")
5
public class User {
6
    // ... 字段定义 ...
7

8
    @ManyToMany(fetch = FetchType.EAGER)
9
    @JoinTable(...)
10
    private Set<Role> roles = new HashSet<>();
11

12
    // ✅ 避免循环引用
13
    @Override
14
    public String toString() {
15
        return "User{id=" + id + ", username=" + username + "}";
16
    }
17

18
    @Override
19
    public boolean equals(Object o) {
20
        if (this == o) return true;
21
        if (!(o instanceof User)) return false;
22
        User user = (User) o;
23
        return id != null && id.equals(user.id);
24
    }
25

26
    @Override
27
    public int hashCode() {
28
        return getClass().hashCode();
29
    }
30
}

3. Permission 实体类(预防性修复)#

1
@Getter
2
@Setter
3
@Entity
4
@Table(name = "sys_permission")
5
public class Permission {
6
    // ... 字段定义 ...
7

8
    @Override
9
    public String toString() {
10
        return "Permission{id=" + id + ", code=" + code + "}";
11
    }
12

13
    @Override
14
    public boolean equals(Object o) {
15
        if (this == o) return true;
16
        if (!(o instanceof Permission)) return false;
17
        Permission p = (Permission) o;
18
        return id != null && id.equals(p.id);
19
    }
20

21
    @Override
22
    public int hashCode() {
23
        return getClass().hashCode();
24
    }
25
}

修复效果#

日志对比#

修复前:

1
=== DEBUG: User loaded ===
2
Username: admin
3
Roles count: 0           ❌
4
========================
5

6
SQL Logs: 5-6 条查询 (包括循环查询)

修复后:

1
仅 1 条 SQL 查询,无额外懒加载
2
Roles count: 1           ✅
3
权限验证通过             ✅

性能提升#

🚀 SQL 查询减少 83% (6 → 1)
🚀 响应时间降低 70% (50-100ms → 10-20ms)
🚀 避免 N+1 查询问题
🚀 减少数据库连接占用

经验总结#

Lombok 使用规范#

❌ 错误用法#

1
// JPA 实体类禁止使用 @Data
2
@Data
3
@Entity
4
public class MyEntity {
5
    @ManyToMany
6
    private Set<OtherEntity> relations;  // toString() 会触发懒加载
7
}

✅ 正确用法#

方案 1: 手动实现 toString

1
@Getter
2
@Setter
3
@Entity
4
public class MyEntity {
5
    @ManyToMany
6
    private Set<OtherEntity> relations;
7

8
    @Override
9
    public String toString() {
10
        return "MyEntity{id=" + id + "}";  // 仅输出基础字段
11
    }
12
}

方案 2: 使用 @ToString.Exclude

1
@Data
2
@Entity
3
public class MyEntity {
4
    @ToString.Exclude  // 排除懒加载字段
5
    @EqualsAndHashCode.Exclude
6
    @ManyToMany
7
    private Set<OtherEntity> relations;
8
}

JPA 实体类最佳实践#

toString: 仅输出基础字段,不访问关联字段
equals/hashCode: 仅使用 ID 比较
双向关联: 必须在一侧排除 toString/equals
懒加载访问: 使用 JOIN FETCH 一次性加载,避免 N+1 查询

代码审查检查清单#

JPA 实体类是否使用了 @Data?
双向关联是否配置了 @ToString.Exclude?
equals/hashCode 是否仅使用 ID?
是否存在调试日志输出整个实体对象?

预防措施#

静态代码分析规则#

1
<!-- Maven PMD/Checkstyle 规则 -->
2
<rule>
3
  <id>NO_DATA_ON_JPA_ENTITY</id>
4
  <message>JPA 实体类禁止使用 @Data 注解</message>
5
  <pattern>@Data.*@Entity</pattern>
6
</rule>

单元测试#

1
@Test
2
void testToStringDoesNotTriggerLazyLoading() {
3
    User user = userRepository.findByUsernameWithRoles("admin").orElseThrow();
4

5
    // 验证 toString 不触发额外查询
6
    User spy = Mockito.spy(user);
7
    String toString = spy.toString();
8

9
    // 验证没有访问懒加载字段
10
    Mockito.verify(spy, Mockito.never()).getRoles();
11
}

参考资料#

总结#

这个 Bug 揭示了一个重要的开发原则:便利性工具(如 Lombok)必须与框架特性(如 JPA 懒加载)配合使用。

核心教训:

在 JPA 实体类上禁用 @Data,手动控制 toString/equals/hashCode
双向关联必须排除循环引用字段
调试日志不要输出整个实体对象
使用静态分析工具强制检查

Lovely firefly!