17370845950

本教程详细指导如何将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的最佳实践是：

1. 使用 FunctionContributor 注册自定义 SQL 函数： 定义一个实现了FunctionContributor接口的类，并在其中注册rlike函数。这个函数将负责生成针对不同方言的SQL片段，并指定其返回类型（例如Boolean）。
2. 通过 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