在 Hibernate 6（Spring Boot 3）中，使用 @JavaType 或 @Convert 映射自定义状态类（如 CustomStatus）后，JPQL 查询中直接用字符串比较（如 status = 'ARCHIVED'）会失败，根本原因是 JPQL 操作符右侧需与属性类型一致——即必须传入 CustomStatus 实例而非 String。
在 hibernate 6（spring boot 3）中，使用 `@javatype` 或 `@convert` 映射自定义状态类（如 `customstatus`）后，jpql 查询中直接用字符串比较（如 `status = 'archived'`）会失败，根本原因是 jpql 操作符右侧需与属性类型一致——即必须传入 `customstatus` 实例而非 `string`。
Hibernate 6 对 JPQL 类型安全要求显著增强：它严格校验查询表达式中左右操作数的 Java 类型一致性。当你在 JPQL 中写 status = 'ARCHIVED' 时，左侧 status 是 CustomStatus 类型路径（BasicSqmPathSource<customstatus></customstatus>），而右侧字面量 'ARCHIVED' 被解析为 String 类型，导致 Can't compare test expression of type [...] with element of type [basicType@4(java.lang.String,12)] 运行时异常。
✅ 正确做法是在 JPQL 中保持类型对齐，即所有参数均以 CustomStatus 实例形式传入：
@Repository
public interface BaseEntityRepository extends JpaRepository<BaseEntity, Integer> {
@Query("SELECT b FROM BaseEntity b WHERE b.status = :status")
List<BaseEntity> findByStatus(@Param("status") CustomStatus status);
@Query("SELECT b FROM BaseEntity b WHERE b.status NOT IN :statuses")
List<BaseEntity> findByStatusNotIn(@Param("statuses") List<CustomStatus> statuses);
// 使用默认方法封装常用状态值，提升可读性与复用性
default List<BaseEntity> findArchived() {
return findByStatus(new CustomStatus("ARCHIVED"));
}
default List<BaseEntity> findActive() {
return findByStatusNotIn(List.of(
new CustomStatus("ARCHIVED"),
new CustomStatus("CANCELLED")
));
}
}⚠️ 注意事项：
-
勿混用原生 SQL 习惯：JPQL 不是 SQL，不支持隐式类型转换；
status = 'ARCHIVED'在 JPQL 中非法，即使底层数据库字段是VARCHAR。 -
@AttributeConverter仅影响持久化/读取，不影响 JPQL 解析逻辑：即使你已正确实现CustomStatusAttributeConverter，JPQL 仍要求查询参数为CustomStatus类型。 -
避免
@Embedded的过度设计：虽然将CustomStatus改为@Embeddable并通过status.name = 'ARCHIVED'查询可行，但需破坏其不可变性（name字段必须非final+ 提供 setter），且丧失领域语义清晰性，不推荐作为首选方案。 -
建议补充
equals()/hashCode()：为CustomStatus添加标准重写，确保集合操作与缓存行为正确：
public class CustomStatus implements Serializable {
private final String name;
public CustomStatus(String name) {
this.name = Objects.requireNonNull(name);
}
public String getName() { return name; }
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof CustomStatus)) return false;
CustomStatus that = (CustomStatus) o;
return Objects.equals(name, that.name);
}
@Override
public int hashCode() {
return Objects.hash(name);
}
}总结：Hibernate 6 的类型安全机制要求 JPQL 查询严格遵循实体属性的 Java 类型。解决 CustomStatus 查询问题的关键不是修改映射方式，而是调整查询写法——始终以 CustomStatus 实例作为参数传入 JPQL，辅以默认方法封装业务语义，即可兼顾类型安全、可维护性与开发效率。
