Hibernate @Filter未按预期生效问题排查求助

我在实体类上定义了Hibernate的@Filter注解实现租户数据隔离，但测试代码中启用过滤器后，JPQL查询仍返回全部数据，不符合预期。

实体类代码：

@Entity
@FilterDef(
    name = "tenantFilter",
    parameters = [ParamDef(name = "tenantId", type = "string")],
)
@Filters(
    value = [
        Filter(name = "tenantFilter", condition = "tenant_id = :tenantId")
    ]
)
class DemoEntity {
   lateinit var tenantId: String
}

测试代码：

var demoEntity = DemoEntity()
demoEntity.id = "1"
demoEntity.tenantId = "tenant1"
demoRepository.save(demoEntity)
demoEntity = DemoEntity()
demoEntity.id = "2"
demoEntity.tenantId = "tenant2"
demoRepository.save(demoEntity)

val session = entityManager.unwrap(Session::class.java)
val enableFilter = session.enableFilter("tenantFilter")
enableFilter.setParameter("tenantId", "tenant1")
val query = entityManager.createQuery("from DemoEntity ").resultList
session.disableFilter("tenantFilter")

println(query)

输出结果返回了两个实体，预期仅返回tenantId=tenant1的实体。

核心原因 #

Hibernate的@Filter默认仅对实体直接加载（find()/get()）和关联查询生效，直接通过EntityManager.createQuery()执行的JPQL不会自动绑定已启用的过滤器；同时缺失事务上下文也可能导致过滤器状态无法正确生效。

解决办法 #

1. 使用Hibernate Session创建查询

启用过滤器后，直接通过Session创建并执行查询，确保过滤器逻辑被应用：

val session = entityManager.unwrap(Session::class.java)
session.enableFilter("tenantFilter").setParameter("tenantId", "tenant1")
// 改用Session创建JPQL查询
val resultList = session.createQuery("from DemoEntity").list()
session.disableFilter("tenantFilter")

println(resultList)

2. 给测试代码添加事务上下文

过滤器的生效依赖于Session的事务绑定，给测试方法添加@Transactional注解（Spring环境），或者手动开启/提交事务：

entityManager.transaction.begin()
val session = entityManager.unwrap(Session::class.java)
session.enableFilter("tenantFilter").setParameter("tenantId", "tenant1")
val resultList = session.createQuery("from DemoEntity").list()
session.disableFilter("tenantFilter")
entityManager.transaction.commit()

println(resultList)

3. 检查实体列映射一致性

确保@Filter的condition中使用的列名和数据库实际列名一致：

• 如果实体属性tenantId未自定义列名，Hibernate默认命名策略会生成tenantid（驼峰转下划线可能因配置不同而变化），此时需将condition改为tenantid = :tenantId；
• 如果已添加@Column(name = "tenant_id")，则当前condition是正确的。

4. 手动在JPQL中添加过滤条件

如果不需要依赖@Filter机制，也可以直接在JPQL中显式指定过滤条件：

val query = entityManager.createQuery("from DemoEntity where tenantId = :tenantId")
query.setParameter("tenantId", "tenant1")
val resultList = query.resultList

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