JPA查询报错UnknownEntityException：无法解析UserEntity实体求助

问题根源 #

你遇到的异常本质是JPQL中引用的实体名称和Hibernate注册的实体名称不匹配：

• 当你给@Entity注解指定了name参数时，Hibernate会将该参数值作为实体的JPQL标识符，不再默认使用类名（UserEntity）。
• 如果实体名称包含-这类特殊字符，直接写入JPQL会触发语法错误——JPQL标识符规则不允许包含连字符，导致解析器无法识别实体。

解决办法 #

方法1：用反引号包裹带特殊字符的实体名 #

JPQL支持用反引号（`）包裹包含特殊字符的实体名，让Hibernate正确解析。假设你的@Entity(name = "user-entity")，修改查询语句如下：

@Query(value = """
        SELECT u FROM `user-entity` u WHERE
            u.id NOT LIKE :user_id AND
            u.is_account_confirmed = true AND
            u.id NOT IN (SELECT f.friends AS fri FROM `user-entity` f WHERE fri.id = :user_id)""")
List<UserEntity> findAllNonFriendUsers(@Param("user_id") String id);

方法2：用Spring Data JPA的#{#entityName}表达式自动适配 #

Spring Data JPA提供了#{#entityName}表达式，会自动替换为当前实体类注册的名称（即@Entity的name参数值，无指定时为类名），无需手动处理特殊字符：

@Query(value = """
        SELECT u FROM #{#entityName} u WHERE
            u.id NOT LIKE :user_id AND
            u.is_account_confirmed = true AND
            u.id NOT IN (SELECT f.friends AS fri FROM #{#entityName} f WHERE fri.id = :user_id)""")
List<UserEntity> findAllNonFriendUsers(@Param("user_id") String id);

这种方式更灵活，后续修改实体名称时无需同步修改JPQL语句。

补充说明 #

当你移除@Entity的name参数时，Hibernate默认使用实体类的简单类名作为JPQL标识符，所以原查询语句能正常运行——这也是为什么移除该参数后异常消失的原因。

内容的提问来源于stack exchange，提问作者Mateusz Wołek