Hibernate枚举比较抛出Query SemanticException：无法解析路径表达式

问题原因 #

直接在HQL语句中硬编码全限定枚举常量（如com.example.entity.security.AccountStatus.Description.ACTIVE）会触发org.hibernate.query.SemanticException，核心原因是HQL解析器会将点分隔的表达式识别为实体属性路径，而非Java枚举常量。它会尝试从user.accountStatus.description之后继续解析路径，自然找不到对应的实体关联，因此抛出“无法解析路径表达式”的错误。

而直接使用字符串'ACTIVE'能正常运行，是因为Hibernate会自动将该字符串字面量与枚举字段的存储值（默认是枚举的name()）做匹配，无需解析路径。

解决方案 #

1. 参数绑定（推荐） #

将枚举作为方法参数传入，既符合JPA规范，又避免硬编码，同时具备类型安全性：

@Repository
public interface UserAccountRepository extends JpaRepository<UserAccount, Long> {

    @EntityGraph(type = EntityGraph.EntityGraphType.FETCH, attributePaths = {
            "accountStatus"
    })
    @Query("""
            SELECT user
            FROM UserAccount user
            WHERE user.userId = ?1
            AND user.accountStatus.description = ?2
            """)
    Optional<UserAccount> findActiveByUserId(Long userId, AccountStatus.Description status);
}

调用时直接传入AccountStatus.Description.ACTIVE即可。

2. 命名参数绑定 #

如果需要更清晰的参数语义，可以使用命名参数：

@Repository
public interface UserAccountRepository extends JpaRepository<UserAccount, Long> {

    @EntityGraph(type = EntityGraph.EntityGraphType.FETCH, attributePaths = {
            "accountStatus"
    })
    @Query("""
            SELECT user
            FROM UserAccount user
            WHERE user.userId = :userId
            AND user.accountStatus.description = :activeStatus
            """)
    Optional<UserAccount> findActiveByUserId(@Param("userId") Long userId, 
                                            @Param("activeStatus") AccountStatus.Description activeStatus);
}

3. Hibernate特定枚举引用（不推荐，仅兼容Hibernate） #

Hibernate支持将内部枚举的点.替换为美元符号$，让解析器识别为枚举常量而非路径：

@Repository
public interface UserAccountRepository extends JpaRepository<UserAccount, Long> {

    @EntityGraph(type = EntityGraph.EntityGraphType.FETCH, attributePaths = {
            "accountStatus"
    })
    @Query("""
            SELECT user
            FROM UserAccount user
            WHERE user.userId = ?1
            AND user.accountStatus.description = com.example.entity.security.AccountStatus$Description.ACTIVE
            """)
    Optional<UserAccount> findActiveByUserId(Long userId);
}

这种方式依赖Hibernate实现，不具备JPA通用性，因此优先推荐参数绑定方案。

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