本文旨在指导开发者如何将hibernate 5中自定义sql谓词（如rlike）的实现迁移至hibernate 6。针对hibernate 6引入的sqm（semantic query model）层，文章重点介绍了一种更简洁、推荐的方案：通过`functioncontributor`注册返回布尔值的自定义sql函数，并结合jpa criteria api进行使用。该方法有效简化了跨方言的复杂逻辑处理，提升了代码的可维护性与可读性。
引言：Hibernate 5到Hibernate 6自定义谓词的挑战
在Hibernate 5中，开发者通常通过扩展org.hibernate.query.criteria.internal.predicate.AbstractSimplePredicate并重写其render(RenderingContext)方法来创建自定义的SQL谓词。这种方式允许直接在Java代码中根据当前的数据库方言（Dialect）拼接SQL字符串，从而实现特定的查询逻辑，例如处理正则表达式匹配（RLIKE）。
然而，Hibernate 6引入了全新的SQM（Semantic Query Model）层，极大地改变了内部查询处理机制。原有的render方法在SQM模型下不再直接适用，导致Hibernate 5中依赖此机制的自定义谓词无法直接迁移。开发者需要一种新的、符合Hibernate 6架构的方式来注册和使用自定义的SQL函数或谓词。
Hibernate 5的实现回顾
为了更好地理解迁移的背景，我们首先回顾一下Hibernate 5中实现自定义RLIKE谓词的典型模式。
1. 自定义谓词类 (RLikePredicate)
在Hibernate 5中，RLikePredicate会继承AbstractSimplePredicate，并在render方法中根据不同的数据库方言生成相应的SQL片段。
// 部分Hibernate 5 RLikePredicate实现 (仅为示意)
package fr.cstb.doef.dao.expression;
import org.hibernate.dialect.HSQLDialect;
import org.hibernate.dialect.MySQLDialect;
import org.hibernate.query.criteria.internal.compile.RenderingContext;
import org.hibernate.query.criteria.internal.expression.LiteralExpression;
import org.hibernate.query.criteria.internal.predicate.AbstractSimplePredicate;
import javax.persistence.criteria.Expression;
import javax.persistence.criteria.CriteriaBuilder;
public class RLikePredicate extends AbstractSimplePredicate {
private final Expression matchExpression;
private final Expression pattern;
public RLikePredicate(CriteriaBuilder criteriaBuilder, Expression matchExpression, Expression pattern) {
super((CriteriaBuilderImpl) criteriaBuilder); // 假设CriteriaBuilderImpl可用
this.matchExpression = matchExpression;
this.pattern = pattern;
}
@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(((Renderable) getPattern()).render(renderingContext)) // 简化处理
.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(((Renderable) getPattern()).render(renderingContext)) // 简化处理
.append(")").append(operator);
} else {
throw new UnsupportedOperationException("Unsupported dialect.");
}
return buffer.toString();
}
// ... 其他方法
} 2. 方言中注册SQL函数
为了让上述rlike函数能够被识别，还需要在对应的Dialect中注册它。
// HSQLDialect 示例
public class HSQLIntBooleanDialect extends HSQLDialect {
public HSQLIntBooleanDialect() {
super();
// 注意：这里返回的是INTEGER，但实际需要的是布尔逻辑
registerFunction("rlike", new SQLFunctionTemplate(StandardBasicTypes.INTEGER, "regexp_substring (?1, ?2) "));
}
}
// MySQLDialect 示例
public class MySQL5IntBooleanDialect extends MySQL5Dialect {
public MySQL5IntBooleanDialect() {
super();
// 注意：这里返回的是INTEGER，但实际需要的是布尔逻辑
registerFunction("rlike", new SQLFunctionTemplate(StandardBasicTypes.INTEGER, "(?1 RLIKE ?2)"));
}
}这种方法在Hibernate 5中工作良好，但其缺点是自定义谓词类需要了解并处理所有支持方言的SQL生成逻辑，导致代码耦合度较高。
Hibernate 6中的新范式：SQM与FunctionContributor
Hibernate 6通过SQM层将HQL/JPQL查询转换为一个抽象的语义模型，然后再将该模型翻译成特定数据库的SQL。这意味着直接操作SQL字符串的render方法不再是首选。
在Hibernate 6中，扩展自定义SQL函数和谓词的推荐方式是使用org.hibernate.boot.model.FunctionContributor接口。这个接口允许开发者在Hibernate启动时注册自定义的SQL函数，并将这些函数集成到SQM模型中。
推荐的Hibernate 6实现方法：注册布尔型SQL函数
最简洁且符合Hibernate 6架构的解决方案是：将RLIKE逻辑封装为一个返回布尔值的SQL函数，并通过FunctionContributor注册到Hibernate中。
1. 实现 FunctionContributor
创建一个实现FunctionContributor接口的类，并在其中注册rlike函数。关键在于指定函数的返回类型为BOOLEAN。
package com.example.hibernate6;
import org.hibernate.boot.model.FunctionContributor;
import org.hibernate.boot.model.FunctionContributions;
import org.hibernate.type.StandardBasicTypes;
public class CustomFunctionContributor implements FunctionContributor {
@Override
public void contributeFunctions(FunctionContributions functionContributions) {
// 注册一个名为 "rlike" 的函数
// "?1 rlike ?2" 是一个模式字符串，表示函数接受两个参数，并以 "rlike" 操作符连接
// 返回类型指定为 BOOLEAN
functionContributions.getFunctionRegistry().registerPattern(
"rlike",
"?1 rlike ?2",
functionContributions.getTypeConfiguration().getBasicTypeRegistry().resolve(StandardBasicTypes.BOOLEAN)
);
}
}配置 FunctionContributor： 为了让Hibernate 能够发现并加载这个 FunctionContributor，你需要在 META-INF/services/org.hibernate.boot.model.FunctionContributor 文件中声明它：
com.example.hibernate6.CustomFunctionContributor
2. 在 JPA Criteria API 中使用
一旦rlike函数被注册为返回布尔类型，你就可以在JPA Criteria API中以非常简洁的方式使用它，就像使用内置函数一样：
import jakarta.persistence.criteria.CriteriaBuilder;
import jakarta.persistence.criteria.CriteriaQuery;
import jakarta.persistence.criteria.Root;
import jakarta.persistence.EntityManager;
import jakarta.persistence.TypedQuery;
// ... 假设你已经有了EntityManager
public class RLikeCriteriaExample {
public static void main(String[] args) {
EntityManager em = getEntityManager(); // 获取EntityManager实例
CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery cq = cb.createQuery(MyEntity.class);
Root from = cq.from(MyEntity.class);
// 使用 criteriaBuilder.function 调用自定义的 "rlike" 函数
// 并将其结果（布尔值）传递给 criteriaBuilder.isTrue
cq.where(cb.isTrue(
cb.function(
"rlike",
Boolean.class, // 指定函数返回类型为 Boolean
from.get("columnName"), // 第一个参数：要匹配的列
cb.literal(".*regex.*") // 第二个参数：正则表达式字面量
)
));
TypedQuery query = em.createQuery(cq);
query.getResultList().forEach(System.out::println);
em.close();
}
private static EntityManager getEntityManager() {
// 实际应用中需要配置和获取EntityManagerFactory
// 这里仅为示例
return null;
}
} 这种方式的优点在于：
- 简洁性： Java代码无需关注SQL的拼接细节，只需调用函数。
- 可移植性： FunctionContributor注册的是逻辑函数，具体的SQL实现由数据库方言处理。
- 集成度高： 与JPA Criteria API无缝集成，符合标准用法。
3. 处理方言差异：在 Dialect 中注册具体的SQL函数
尽管FunctionContributor注册了通用的函数模式，但不同数据库对RLIKE的实现可能有所不同。为了确保在不同数据库下方言能够正确地将rlike函数翻译成原生SQL，你需要在各自的Dialect中注册具体的SQLFunction。
HSQL 方言示例：
import org.hibernate.dialect.HSQLDialect;
import org.hibernate.dialect.function.SQLFunctionTemplate;
import org.hibernate.type.StandardBasicTypes;
public class HSQLCustomDialect extends HSQLDialect {
public HSQLCustomDialect() {
super();
// HSQLDB 使用 regexp_substring，并判断 IS NOT NULL 来模拟布尔结果
registerFunction("rlike", new SQLFunctionTemplate(StandardBasicTypes.BOOLEAN, "regexp_substring (?1, ?2) IS NOT NULL"));
}
}MySQL 方言示例：
import org.hibernate.dialect.MySQL8Dialect; // 或 MySQL5Dialect
import org.hibernate.dialect.function.SQLFunctionTemplate;
import org.hibernate.type.StandardBasicTypes;
public class MySQLCustomDialect extends MySQL8Dialect {
public MySQLCustomDialect() {
super();
// MySQL 的 RLIKE 操作符本身返回 0 或 1，可以直接作为布尔值处理
registerFunction("rlike", new SQLFunctionTemplate(StandardBasicTypes.BOOLEAN, "(?1 RLIKE ?2)"));
}
}注意事项：
- 确保在Dialect中注册的SQLFunctionTemplate返回的类型与FunctionContributor中声明的类型（StandardBasicTypes.BOOLEAN）一致，或者能够被Hibernate正确映射为布尔值。
- 对于MySQL，RLIKE返回0或1，Hibernate的StandardBasicTypes.BOOLEAN通常能正确处理这种映射。对于HSQL，regexp_substring返回字符串或null，通过IS NOT NULL将其转换为布尔结果是常见的做法。
对比用户尝试的H6解决方案 (SqmPredicate)
在问题描述中，用户提供了一个尝试性的Hibernate 6解决方案，通过扩展AbstractNegatableSqmPredicate并重写accept(SemanticQueryWalker
// 用户尝试的Hibernate 6 RLikePredicate 实现 (部分)
public class RLikePredicate extends AbstractNegatableSqmPredicate implements Serializable {
// ... 构造函数和字段
@Override
public T accept(SemanticQueryWalker walker) {
if (walker instanceof SqmTranslator) {
Dialect dialect = ((SqmTranslator) walker).getCreationContext().getSessionFactory().getJdbcServices().getDialect();
if (dialect instanceof HSQLDialect) {
// HSQL 方言生成 SqmNullnessPredicate
return walker.visitIsNullPredicate(new SqmNullnessPredicate(function, !isNegated(), nodeBuilder()));
} else {
// 其他方言（如 MySQL）生成 SqmComparisonPredicate
return walker.visitComparisonPredicate(new SqmComparisonPredicate(
function,
isNegated() ? ComparisonOperator.NOT_EQUAL : ComparisonOperator.EQUAL,
nodeBuilder().literal(1),
nodeBuilder()
));
}
}
return function.accept(walker);
}
// ... 其他方法
} 这种方法虽然在技术上可行，但它将方言相关的SQL生成逻辑（通过SqmNullnessPredicate或SqmComparisonPredicate）耦合到了自定义谓词的Java类中。这与Hibernate 6将SQL生成职责下放给Dialect和SQM翻译器的设计理念相悖，导致：
- 代码复杂性： 自定义谓词类需要处理不同方言的判断和SQM节点构建。
- 维护成本： 每当支持新的方言或SQL逻辑需要调整时，都需要修改这个自定义谓词类。
相比之下，通过FunctionContributor注册布尔型SQL函数的方法更加简洁和模块化，它将方言差异的处理完全委托给了Dialect中的SQLFunction注册，使得自定义谓词的使用者无需关心底层SQL细节。
总结与最佳实践
从Hibernate 5迁移到Hibernate 6时，处理自定义SQL谓词（如RLIKE）的核心思想是适应Hibernate 6的SQM模型，并利用其提供的扩展点。
推荐的最佳实践是：
- 使用 FunctionContributor 注册自定义的SQL函数。 将自定义逻辑封装成一个返回布尔值的SQL函数，并在FunctionContributor中声明其通用模式和返回类型。
- 在 Dialect 中注册具体的 SQLFunction。 根据不同数据库的特性，在各自的Dialect中实现该SQL函数的具体SQL转换逻辑。
- 在 JPA Criteria API 中通过 criteriaBuilder.function 调用。 结合 criteriaBuilder.isTrue() 或 criteriaBuilder.isFalse() 来使用这些布尔型函数。
这种方法不仅解决了Hibernate 6的迁移问题，还提供了一种更优雅、更符合Hibernate架构的设计模式，使得自定义SQL功能在不同数据库间具有更好的可移植性和更低的维护成本。
