Hibernate 5.6.6.Final第二次及后续调用报参数类型不匹配异常

基于Hibernate 5.6.6.Final版本开发的应用，DAO/Repository层查询方法首次调用无异常，从第二次调用开始持续抛出如下错误：

Parameter value [\] did not match expected type [java.lang.String (n/a)]; nested exception is java.lang.IllegalArgumentException: Parameter value [\] did not match expected type [java.lang.String (n/a)]

异常核心提示为：绑定的参数值为单独的反斜杠\，与方法声明的期望参数类型java.lang.String不匹配，嵌套抛出非法参数异常。

• Hibernate 5.6.6.Final版本存在已知的参数解析器缓存污染回归bug：该版本的HQL/JPQL参数解析逻辑中，转义状态标记没有在单次查询执行完成后重置。当首次查询传入的参数末尾携带未闭合的转义反斜杠时，解析器会将转义状态残留在全局执行缓存中，第二次查询执行参数绑定时，解析器会把残留的反斜杠\识别为新传入的参数值，触发类型匹配校验失败。
• 自定义Hibernate类型转换器状态泄漏：如果自定义了字符串相关的UserType或AttributeConverter，且转换器为单例生命周期、内部用成员变量存储参数解析的临时值，首次调用处理带反斜杠的参数时，若未清空成员变量中存储的\值，后续调用会直接读取到该残留值作为入参绑定。
• 动态HQL拼接导致参数占位符错位：手动拼接HQL语句时如果反斜杠转义处理不当，会把相邻的命名参数占位符或位置参数占位符转义失效。首次执行后语句被Hibernate纳入查询缓存，第二次执行时参数绑定顺序和占位符位置完全错位，把转义用的\错绑到String类型参数位上。

• 第一步：在业务层DAO方法入口打印每次调用的实际入参全量日志，先排除业务代码本身第二次调用时错误传入单独\值的问题。
• 第二步：开启Hibernate参数绑定全量日志，配置参数hibernate.show_sql=true、hibernate.format_sql=true，同时将日志包org.hibernate.type.descriptor.sql的日志级别设置为trace，观察实际绑定到SQL上的参数值，确认异常值是来自业务传入还是Hibernate内部生成。
• 第三步：排查项目中所有自定义Hibernate类型转换器、单例生命周期的DAO组件、Hibernate配置类，检查这些类中是否存在用来存储单次请求参数临时值的成员变量，确认是否存在多请求间的状态共享问题。
• 第四步：检索项目中所有涉及模糊查询（like）的逻辑，检查是否存在手动拼接%、反斜杠转义符时漏写闭合的代码，例如手动拼接转义后缀时只写了单个\的错误写法。

• 优先升级Hibernate版本到5.6.7.Final及以上，该参数解析缓存污染的问题是5.6.6版本专属的回归bug，官方在5.6.7版本已经修复了转义状态未重置的缺陷。
• 若暂时无法升级版本，所有传入Hibernate查询的字符串参数，在绑定前手动做反斜杠二次转义，将单个\替换为\\，避免触发解析器转义状态异常，参考代码如下：

  if (queryParam != null) {
      queryParam = queryParam.replace("\\", "\\\\");
  }
  

• 整改所有自定义Hibernate类型转换器，将内部存储临时解析值的成员变量全部改为方法内局部变量，禁止在单例生命周期的转换器/DAO组件中用成员变量存储单次请求相关的临时数据，避免多调用间的状态泄漏。
• 禁止手动拼接like查询的转义逻辑，统一使用Hibernate Criteria API自带的转义能力处理模糊查询，参考写法如下：

  // 无需手动处理反斜杠转义，由Hibernate内部统一处理
  Predicate likePredicate = cb.like(root.get("userName"), "%" + keyword + "%", '\\');
  

内容的提问来源于stack exchange，提问作者Prashant kamble