本教程详细指导如何将Hibernate 5中自定义的SQL Predicate和Expression迁移到Hibernate 6。针对Hibernate 6的SQM模型，文章重点介绍了利用`FunctionContributor`注册自定义SQL函数，并通过`CriteriaBuilder.function`将其集成到JPA Criteria查询中，从而替代Hibernate 5中基于`Renderable`的自定义渲染逻辑，实现更简洁、高效且兼容多方言的自定义查询。
引言：Hibernate 5 与 Hibernate 6 自定义查询的范式转变
在数据持久化层，开发者经常需要执行一些标准JPA Criteria API无法直接表达的复杂或特定于数据库的查询逻辑，例如正则表达式匹配（RLIKE）。在Hibernate 5中，实现自定义SQL Predicate或Expression通常涉及创建自定义的javax.persistence.criteria.Predicate实现，并重写其render(boolean isNegated, RenderingContext renderingContext)方法来手动构建SQL字符串。这种方法虽然灵活，但将SQL渲染逻辑紧密耦合到Predicate类中，且依赖于Hibernate内部的RenderingContext，在Hibernate版本升级时容易出现兼容性问题。
Hibernate 6引入了全新的SQM（Semantic Query Model）模型，对内部查询处理机制进行了重大重构。这意味着Hibernate 5中直接操作RenderingContext的方式不再适用或被推荐。本文将详细探讨从Hibernate 5到Hibernate 6迁移自定义Predicate的挑战，并提供一个推荐的、更符合Hibernate 6设计哲学的解决方案。
Hibernate 5 中的自定义 Predicate 机制回顾
在Hibernate 5中，一个典型的自定义Predicate（例如用于实现RLIKE功能的RLikePredicate）会继承自AbstractSimplePredicate，并重写render方法。在这个方法内部，开发者需要根据当前使用的数据库方言（通过renderingContext.getDialect()获取）手动拼接SQL字符串。同时，为了让数据库识别自定义函数，还需要在对应的Dialect中注册SQLFunctionTemplate。
以下是Hibernate 5中RLikePredicate的简化示例，展示了其核心渲染逻辑：
// HSQLDialect 注册自定义函数
public class HSQLIntBooleanDialect extends HSQLDialect {
public HSQLIntBooleanDialect() {
super();
// 注册 'rlike' 函数，映射到 HSQL 的 regexp_substring
registerFunction("rlike", new SQLFunctionTemplate(StandardBasicTypes.INTEGER, "regexp_substring (?1, ?2) "));
}
}
// MySQLDialect 注册自定义函数
public class MySQL5IntBooleanDialect extends MySQL5Dialect {
public MySQL5IntBooleanDialect() {
super();
// 注册 'rlike' 函数，映射到 MySQL 的 RLIKE
registerFunction("rlike", new SQLFunctionTemplate(StandardBasicTypes.INTEGER, "(?1 RLIKE ?2)"));
}
}
// Hibernate 5 RLikePredicate 的 render 方法片段
public class RLikePredicate extends AbstractSimplePredicate implements Serializable {
// ... 构造器和成员变量 ...
@Override
public String render(boolean isNegated, RenderingContext renderingContext) {
StringBuilder buffer = new StringBuilder();
// 根据方言手动拼接 SQL
if (renderingContext.getDialect() instanceof HSQLDialect) {
final String operator = isNegated ? " IS NULL" : " IS NOT NULL";
buffer.append("rlike (").append(((Renderable) getMatchExpression()).render(renderingContext))
.append(",")
.append(escapeSqlRegex(renderingContext, String::valueOf)).append(")").append(operator);
} else if (renderingContext.getDialect() instanceof MySQLDialect) {
final String operator = isNegated ? " != 1" : " = 1";
buffer.append("rlike (").append(((Renderable) getMatchExpression()).render(renderingContext))
.append(",")
.append(escapeSqlRegex(renderingContext, String::valueOf)).append(")").append(operator);
} else {
throw new UnsupportedOperationException("Unsupported dialect.");
}
return buffer.toString();
}
// ... 其他方法 ...
}这种方式的缺点在于，RLikePredicate不仅定义了Predicate的结构，还包含了复杂的SQL生成逻辑，并且需要对Hibernate内部的Renderable和RenderingContext有深入了解。
Hibernate 6 的新范式：SQM 与 FunctionContributor
Hibernate 6引入了SQM（Semantic Query Model），这是一个更抽象、更稳定的查询模型，旨在将查询的语义表示与具体的SQL生成解耦。在SQM模型下，直接重写render方法来生成SQL的方式不再是推荐做法。
取而代之的是，Hibernate 6鼓励通过FunctionContributor接口来注册自定义的SQL函数。FunctionContributor允许开发者在Hibernate启动时向其函数注册表添加自定义函数，这些函数随后可以通过CriteriaBuilder或HQL/JPQL直接使用。这种方法将自定义SQL逻辑从业务Predicate中分离出来，使得Predicate的定义更简洁，SQL生成更集中和可维护。
推荐的 Hibernate 6 解决方案
在Hibernate 6中，实现自定义RLIKE Predicate的最佳实践是：
- 使用 FunctionContributor 注册自定义 SQL 函数： 定义一个实现了FunctionContributor接口的类，并在其中注册rlike函数。这个函数将负责生成针对不同方言的SQL片段，并指定其返回类型（例如Boolean）。
- 通过 CriteriaBuilder.function 在 JPA Criteria 中使用： 在构建Criteria查询时，使用criteriaBuilder.function()方法调用已注册的rlike函数，并将其结果转换为Predicate。
1. 注册自定义 SQL 函数
首先，创建一个实现FunctionContributor接口的类。这个类通常通过META-INF/services/org.hibernate.boot.model.FunctionContributor文件或Spring Boot的自动配置机制被Hibernate发现和加载。
import org.hibernate.boot.model.FunctionContributions;
import org.hibernate.boot.model.FunctionContributor;
import org.hibernate.dialect.HSQLDialect;
import org.hibernate.type.StandardBasicTypes;
import org.hibernate.query.sqm.function.SqmFunctionRegistry;
import org.hibernate.query.sqm.function.PatternBasedSqmFunctionDescriptor;
import org.hibernate.query.sqm.function.AbstractSqmFunctionDescriptor;
import org.hibernate.engine.spi.SessionFactoryImplementor;
import org.hibernate.query.sqm.produce.function.StandardFunctionArgumentTypeResolvers;
import org.hibernate.query.sqm.tree.expression.SqmExpression;
import org.hibernate.query.sqm.produce.function.FunctionReturnTypeResolver;
import org.hibernate.type.Type;
import java.util.List;
public class MyCustomFunctionContributor implements FunctionContributor {
@Override
public void contributeFunctions(FunctionContributions functionContributions) {
// 获取类型配置
var typeConfiguration = functionContributions.getTypeConfiguration();
var basicTypeRegistry = typeConfiguration.getBasicTypeRegistry();
// 注册一个名为 "rlike" 的函数，它返回一个布尔值
// 对于简单的SQL模式，可以使用 registerPattern
// functionContributions.getFunctionRegistry().registerPattern(
// "rlike",
// "?1 rlike ?2", // 适用于MySQL等直接支持 RLIKE 的数据库
// basicTypeRegistry.resolve(StandardBasicTypes.BOOLEAN)
// );
// 对于需要根据方言生成不同SQL的复杂情况，需要注册一个自定义的 SQLFunction
functionContributions.getFunctionRegistry().register(
"rlike",
new AbstractSqmFunctionDescriptor("rlike", StandardFunctionArgumentTypeResolvers.ANY_TYPE, new FunctionReturnTypeResolver() {
@Override
public Type resolveFunctionReturnType(Type firstArgumentType, List arguments, SessionFactoryImplementor sessionFactory) {
return basicTypeRegistry.resolve(StandardBasicTypes.BOOLEAN); // 始终返回布尔类型
}
}) {
@Override
public String render(List arguments, SqmFunctionRegistry functionRegistry, SessionFactoryImplementor sessionFactory) {
// 获取当前方言
var dialect = sessionFactory.getJdbcServices().getDialect();
String firstArg = functionRegistry.render(arguments.get(0), sessionFactory);
String secondArg = functionRegistry.render(arguments.get(1), sessionFactory);
if (dialect instanceof HSQLDialect) {
// HSQL 使用 regexp_substring 并检查是否为 NULL
return "regexp_substring (" + firstArg + ", " + secondArg + ") IS NOT NULL";
} else {
// MySQL 或其他数据库使用 RLIKE 并检查结果是否为 1 (或直接作为布尔)
return "(" + firstArg + " RLIKE " + secondArg + ") = 1";
}
}
}
);
}
} 说明：
- FunctionContributor 的 contributeFunctions 方法是注册自定义函数的入口。
- functionContributions.getFunctionRegistry().register(...) 用于注册一个自定义的SqmFunctionDescriptor。
- 我们创建了一个匿名内部类`AbstractSqmFunction
