Hibernate 6中自定义SQL函数与谓词的迁移与实现指南

本文旨在指导开发者如何将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;// ... 假设你已经有了EntityManagerpublic 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;    }}

这种方式的优点在于：

Revid AI

AI短视频生成平台

96 查看详情 简洁性： 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; // 或 MySQL5Dialectimport 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 walker)方法来实现RLikePredicate。

// 用户尝试的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功能在不同数据库间具有更好的可移植性和更低的维护成本。

以上就是Hibernate 6中自定义SQL函数与谓词的迁移与实现指南的详细内容，更多请关注创想鸟其它相关文章！