Hibernate 6使用YesNoConverter映射布尔值时JPA派生查询失效

问题场景 #

我定义了User实体类，数据库中deleted列是字符类型，取值为'Y'或'N'，通过YesNoConverter将实体的布尔属性deleted与数据库列做转换：

public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    // 省略其他属性
    
    @Column(name = "deleted")
    @Convert(converter= YesNoConverter.class)
    private boolean deleted;
}

使用Spring Data JPA的派生查询方法时触发异常：

public interface UserRepository extends JpaRepository<User,Long> {
    List<User> findByDeletedFalse();
}

异常提示：argument of NOT must be type boolean, not type character，生成的SQL为：

select u1_0.id,u1_0.deleted,u1_0.first_name,u1_0.home_address_id,u1_0.last_name,u1_0.work_address_id from users u1_0 where not(u1_0.deleted)

但改用JPQL查询则能正常执行：

@Query("select u from User u where u.deleted=false")
List<User> findByDeletedFalse();

环境版本：Spring Boot v3.0.2，Hibernate v6.1.7.Final

原因分析 #

Spring Data JPA的派生查询在解析带@Convert注解的布尔属性时，没有正确应用转换器的映射逻辑，直接生成了针对布尔类型的SQL表达式（not(u1_0.deleted)），但数据库中该列实际是字符类型，导致数据库无法识别该逻辑，抛出类型不匹配错误。而JPQL查询是基于实体的布尔属性进行解析，Hibernate会自动应用转换器，将u.deleted=false转换为数据库列等于'N'的正确SQL。

解决方案 #

方案1：使用JPQL查询替代派生查询 #

直接通过@Query注解编写JPQL语句，让Hibernate正确处理转换器逻辑，这是最直接的验证可行方案：

@Query("select u from User u where u.deleted = false")
List<User> findByDeletedFalse();

方案2：改用Hibernate特定的类型注解 #

如果项目依赖Hibernate，可以使用其自带的YesNoType替代@Convert，这样Spring Data JPA的派生查询能正确识别类型转换逻辑：

import org.hibernate.annotations.Type;
import org.hibernate.type.YesNoType;

public class User {
    // 省略其他属性
    @Column(name = "deleted")
    @Type(YesNoType.class)
    private boolean deleted;
}

使用该方式后，派生查询findByDeletedFalse()会生成正确的SQL：where u1_0.deleted = 'N'，避免类型不匹配问题。

方案3：调整派生查询方法名（不推荐） #

可以通过方法名明确指定字符值匹配，不过这种方式不够直观，需要手动传入匹配值：

List<User> findByDeletedNot(String deletedValue);

调用时传入"Y"来获取未删除的用户，不过这种方式不如前两种方案简洁易用。

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