1. 概述
使用 Hibernate 这类 ORM 框架，能让我们轻松地把数据库数据映射成对象，但在面对复杂数据模型时，查询的构建却可能变得异常棘手。
多对多关系（@ManyToMany）本身就不简单，更麻烦的是：我们有时需要根据关联关系本身的属性来筛选目标实体。比如，一个用户属于多个群组，但只想查出他是“管理员”的那些群组。
本文将介绍如何使用 Hibernate 提供的 @WhereJoinTable 注解，简单粗暴地解决这类问题。✅
2. 基础的 @ManyToMany 关系
我们先从一个标准的 @ManyToMany 关系开始，构建领域模型、关联实体，并准备测试数据。
2.1. 领域模型
假设我们有两个实体：User 和 Group，它们之间是多对多关系：
@Entity(name = "users")
public class User {
@Id
@GeneratedValue
private Long id;
private String name;
@ManyToMany
private List<Group> groups = new ArrayList<>();
// standard getters and setters
}
@Entity
public class Group {
@Id
@GeneratedValue
private Long id;
private String name;
@ManyToMany(mappedBy = "groups")
private List<User> users = new ArrayList<>();
// standard getters and setters
}
很清晰：一个用户可以加入多个群组，一个群组也能包含多个用户。
2.2. 关联实体
⚠️ 注意：对于 @ManyToMany 关系，数据库层面需要一张关联表（Join Table） 来维护双方的主键关系。
如果关联表只存两个主键，Hibernate 可以自动管理。但一旦你想在关联表里加额外字段（比如角色、加入时间等），就必须显式定义一个关联实体类。
我们来创建 UserGroupRelation 类：
@Entity(name = "r_user_group")
public class UserGroupRelation implements Serializable {
@Id
@Column(name = "user_id", insertable = false, updatable = false)
private Long userId;
@Id
@Column(name = "group_id", insertable = false, updatable = false)
private Long groupId;
@Enumerated(EnumType.STRING)
private UserGroupRole role;
}
这里我们给实体指定了 name = "r_user_group"，后续会用到。
额外字段是 role，表示用户在群组中的角色。先定义枚举：
public enum UserGroupRole {
MEMBER, MODERATOR
}
接着，更新 User 类中的 groups 字段，明确指定使用 r_user_group 表：
@ManyToMany
@JoinTable(
name = "r_user_group",
joinColumns = @JoinColumn(name = "user_id"),
inverseJoinColumns = @JoinColumn(name = "group_id")
)
private List<Group> groups = new ArrayList<>();
2.3. 测试数据
写个简单的 setUp 方法准备测试数据：
public void setUp() {
session = sessionFactory.openSession();
session.beginTransaction();
user1 = new User("user1");
user2 = new User("user2");
user3 = new User("user3");
group1 = new Group("group1");
group2 = new Group("group2");
session.save(group1);
session.save(group2);
session.save(user1);
session.save(user2);
session.save(user3);
saveRelation(user1, group1, UserGroupRole.MODERATOR);
saveRelation(user2, group1, UserGroupRole.MODERATOR);
saveRelation(user3, group1, UserGroupRole.MEMBER);
saveRelation(user1, group2, UserGroupRole.MEMBER);
saveRelation(user2, group2, UserGroupRole.MODERATOR);
}
private void saveRelation(User user, Group group, UserGroupRole role) {
UserGroupRelation relation = new UserGroupRelation(user.getId(), group.getId(), role);
session.save(relation);
session.flush();
session.refresh(user);
session.refresh(group);
}
关键点：
user1是group1的 MODERATOR，但在group2中只是 MEMBER。user2在两个群组中都是 MODERATOR。user3只是group1的普通成员。
3. 多对多关系的查询
模型和数据都准备好了，现在来查数据。
3.1. 普通查询
直接调用 getGroups()，就能拿到用户加入的所有群组：
List<Group> groups = user1.getGroups();
输出：
[Group [name=group1], Group [name=group2]]
但如果我只想查出 user1 是“管理员”的群组呢？传统做法可能得写 HQL 或 Criteria 查询，代码啰嗦还容易踩坑。
3.2. 使用 @WhereJoinTable 实现条件过滤
✅ 正确姿势：使用 @WhereJoinTable 注解，在映射层面直接加 SQL 条件。
我们在 User 类中新增一个字段：
@WhereJoinTable(clause = "role='MODERATOR'")
@ManyToMany
@JoinTable(
name = "r_user_group",
joinColumns = @JoinColumn(name = "user_id"),
inverseJoinColumns = @JoinColumn(name = "group_id")
)
private List<Group> moderatorGroups = new ArrayList<>();
解释一下：
@WhereJoinTable(clause = "role='MODERATOR'")：告诉 Hibernate，只加载role = 'MODERATOR'的关联记录。- 其他注解和
groups字段一致，复用同一张表。
现在，直接调用：
List<Group> groups = user1.getModeratorGroups();
输出：
[Group [name=group1]]
完美！group2 被自动过滤掉了，因为 user1 在其中是 MEMBER。
💡 小贴士：
clause写的是原生 SQL 片段，直接作用于关联表。- 条件字段必须是关联表中的列（如
role），不能是主表或从表的字段。 - 适合静态过滤场景，动态条件建议还是用 QueryDSL 或原生查询。
4. 总结
本文核心就一句话：
✅ 使用 @WhereJoinTable 注解，可以基于关联表的字段对 @ManyToMany 集合进行静态条件过滤，避免手动写复杂查询。
适用场景：
- 多对多关系带状态字段（如角色、状态、有效期）
- 需要按状态懒加载关联数据
- 想减少业务层的查询逻辑，把过滤下沉到映射层
⚠️ 注意事项：
- 不支持动态参数，
clause是硬编码 SQL - 条件字段必须在关联表中存在
- 使用时注意 N+1 查询问题，必要时配合
@Fetch优化
所有示例代码已托管至 GitHub：https://github.com/yourname/hibernate-wherejointable-demo