升级Hibernate 6与Java 17后多输出参数StoredProcedureQuery失效

1. 核心适配要点 #

Hibernate 6对存储过程参数的类型校验和绑定逻辑做了严格调整，旧版本依赖自动推断的写法会失效，必须显式指定参数类型、模式，同时注意Java 17的类型装箱规范。

2. 完整代码实现 #

假设目标存储过程（以MySQL为例）定义如下：

CREATE PROCEDURE get_user_business_data(
    IN user_id INT,
    IN user_role CHAR(1),
    IN department VARCHAR(60),
    OUT total_trans INT,
    OUT total_revenue DECIMAL(12,2)
)
BEGIN
    SELECT COUNT(t.id), SUM(t.amount) 
    INTO total_trans, total_revenue
    FROM transactions t
    WHERE t.user_id = user_id 
      AND t.user_role = user_role 
      AND t.department = department;
END

对应的Java调用代码：

import jakarta.persistence.EntityManager;
import jakarta.persistence.ParameterMode;
import jakarta.persistence.StoredProcedureQuery;

public class ProcedureExecutor {

    private final EntityManager entityManager;

    // Java 17推荐构造注入EntityManager
    public ProcedureExecutor(EntityManager entityManager) {
        this.entityManager = entityManager;
    }

    public BusinessResult fetchUserBusinessData(Integer userId, char userRole, String department) {
        // 创建存储过程查询实例，传入存储过程名称
        StoredProcedureQuery query = entityManager.createStoredProcedureQuery("get_user_business_data");

        // 1. 注册所有参数：必须显式指定Java类型和参数模式
        // IN参数
        query.registerStoredProcedureParameter("user_id", Integer.class, ParameterMode.IN);
        query.registerStoredProcedureParameter("user_role", Character.class, ParameterMode.IN);
        query.registerStoredProcedureParameter("department", String.class, ParameterMode.IN);
        // OUT参数
        query.registerStoredProcedureParameter("total_trans", Integer.class, ParameterMode.OUT);
        query.registerStoredProcedureParameter("total_revenue", Double.class, ParameterMode.OUT);

        // 2. 绑定IN参数值
        query.setParameter("user_id", userId);
        query.setParameter("user_role", userRole); // char自动装箱为Character，适配数据库CHAR类型
        query.setParameter("department", department);

        // 3. 执行存储过程
        query.execute();

        // 4. 获取OUT参数结果
        Integer totalTrans = (Integer) query.getOutputParameterValue("total_trans");
        Double totalRevenue = (Double) query.getOutputParameterValue("total_revenue");

        return new BusinessResult(totalTrans, totalRevenue);
    }

    // 结果封装类
    public static class BusinessResult {
        private final Integer totalTransactions;
        private final Double totalRevenue;

        public BusinessResult(Integer totalTransactions, Double totalRevenue) {
            this.totalTransactions = totalTransactions;
            this.totalRevenue = totalRevenue;
        }

        // Getter方法
        public Integer getTotalTransactions() { return totalTransactions; }
        public Double getTotalRevenue() { return totalRevenue; }
    }
}

3. 版本差异关键注意点 #

• 参数注册必须显式：Hibernate 6不再允许省略参数类型，registerStoredProcedureParameter必须指定对应Java类型，否则会抛出类型不匹配异常。
• char类型处理：数据库CHAR(1)类型必须绑定Character.class，不能用String替代，避免类型转换错误。
• OUT参数获取：必须通过参数名称调用getOutputParameterValue，依赖位置索引的写法在Hibernate 6中会失效。
• 事务上下文：存储过程执行必须在事务内，Spring环境下需给方法添加@Transactional注解，非Spring环境需手动开启事务。

4. 常见问题排查 #

• 参数找不到异常：检查存储过程参数名称与代码注册的是否完全一致（注意数据库大小写规则，比如Oracle区分大小写）。
• 类型转换异常：确保Java类型与数据库参数类型匹配，比如数据库DECIMAL对应Double或BigDecimal，INT对应Integer。
• 执行无结果：确认存储过程本身逻辑正确，可先在数据库客户端测试存储过程是否返回预期值。

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