Spring Boot 3中Hibernate自定义数据类型NULL查询问题及优化咨询

问题背景 #

在Spring Boot 3中使用Hibernate自定义数据类型（AttributeConverter），已完成转换器、注解、验证器、描述器等实现，基础CRUD功能正常，但JPA仓库中的自定义查询无法正常运行：

@Query("SELECT a FROM #{#entityName} a WHERE ((:#{#iValue} IS NULL AND a.value IS NULL) OR a.value = :#{#iValue})")
MyEntity findByValue(@Param("iValue") MyDataType value)

报错信息 #

org.springframework.orm.jpa.JpaSystemException: Could not determine recommended JdbcType for org.example.MyDataType

排查发现：仅当value != null时触发错误，value == null时查询正常。该问题是Hibernate 6中复现的旧BUG，涉及的问题包括Spring Data JPA的#2549，以及Hibernate的HHH-8697、HHH-9901、HHH-9320。

咨询问题 #

1. 需要进行哪些配置或调整，才能让非NULL值的查询正常工作？
2. 是否有比((:#{#iValue} IS NULL AND a.value IS NULL) OR a.value = :#{#iValue})更优雅的写法？a.value = :#{#iValue}无法处理NULL值，Hibernate不会自动转换为IS NULL，未找到其他解决方案。

解决方案 #

1. 修复非NULL值查询的配置调整 #

针对Hibernate 6无法识别自定义类型JDBC映射的问题，可采用以下方案：

• 显式指定JDBC类型：在实体类的目标字段上，通过@Column指定数据库列类型，搭配@JdbcTypeCode明确JDBC类型代码。示例如下（假设自定义类型映射到VARCHAR）：

  @Column(columnDefinition = "VARCHAR(255)")
  @JdbcTypeCode(SqlTypes.VARCHAR)
  private MyDataType value;
  

  需确保AttributeConverter的转换目标类型与指定的JDBC类型完全匹配。
• 改用Hibernate自定义类型接口：放弃AttributeConverter，实现Hibernate的UserType或CompositeUserType接口，完整定义类型的JDBC映射、序列化/反序列化逻辑，再通过@Type注解关联到实体字段。这种方式能让Hibernate完全识别类型的JDBC特性，避免类型推断问题。
• 升级Hibernate版本：查看对应BUG的修复记录，若已有修复版本，直接升级Hibernate ORM（可通过调整Spring Boot父版本间接升级，Spring Boot 3对应Hibernate 6.x系列）。

2. 更优雅的NULL兼容查询写法 #

有两种简洁方式替代原有的分支判断：

• 利用COALESCE函数统一匹配逻辑：将NULL值映射到一个业务上不存在的常量，通过等于判断覆盖NULL和非NULL场景：

  @Query("SELECT a FROM #{#entityName} a WHERE COALESCE(a.value, :nullPlaceholder) = COALESCE(:#{#iValue}, :nullPlaceholder)")
  MyEntity findByValue(@Param("iValue") MyDataType value, @Param("nullPlaceholder") MyDataType nullPlaceholder);
  

  调用时传入一个不会出现在业务数据中的nullPlaceholder实例即可。
• 使用Spring Data JPA派生查询：若无需自定义JPQL，直接定义派生查询方法，Spring Data JPA会自动处理NULL值的匹配逻辑：

  MyEntity findByValue(MyDataType value);
  

  只要自定义类型的转换配置正确，派生查询会自动生成适配SQL：参数为NULL时生成a.value IS NULL，非NULL时生成a.value = ?。

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