Spring Boot中JPA自定义JPQL查询抛出NamedQuery异常求助

问题原因 #

当Spring Data JPA处理带有Sort参数的自定义@Query查询时，框架会自动尝试生成或查找对应的count查询（用于支持潜在的分页场景）。如果你的JPQL查询无法被框架自动解析生成count语句，它会尝试查找命名查询OrderModel.findByMid.count，找不到就抛出异常。

解决方案 #

1. 显式指定JPQL类型的countQuery #

在@Query注解中通过countQuery属性提供对应的JPQL count语句，无需使用原生查询。示例代码：

import org.springframework.data.domain.Sort;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import java.util.List;

public interface OrderRepository extends JpaRepository<OrderModel, Long> {

    @Query(value = "SELECT o FROM OrderModel o WHERE o.mid = :mid",
           countQuery = "SELECT COUNT(o) FROM OrderModel o WHERE o.mid = :mid")
    List<OrderModel> findByMid(@Param("mid") String mid, Sort sort);
}

这种方式直接告诉框架使用你定义的count查询，不会再去查找命名查询，完全符合JPQL的使用要求。

2. 确保JPQL查询符合自动生成规则 #

如果不想手动写countQuery，检查你的JPQL是否是简单的实体查询：

• 避免复杂的JOIN、GROUP BY或子查询（这类场景框架自动生成count容易出错）
• 用@Param明确绑定参数，避免参数解析歧义
  如果你的查询足够简单，框架会自动生成正确的count语句，无需额外配置。

3. 手动定义命名查询 #

在实体类上通过@NamedQueries定义对应的查询和count查询，让框架直接匹配使用：

import javax.persistence.Entity;
import javax.persistence.NamedQueries;
import javax.persistence.NamedQuery;

@Entity
@NamedQueries({
    @NamedQuery(name = "OrderModel.findByMid", 
                query = "SELECT o FROM OrderModel o WHERE o.mid = :mid"),
    @NamedQuery(name = "OrderModel.findByMid.count", 
                query = "SELECT COUNT(o) FROM OrderModel o WHERE o.mid = :mid")
})
public class OrderModel {
    // 实体字段、getter/setter等
}

此时Repository中的方法可以去掉@Query注解，框架会自动匹配命名查询：

List<OrderModel> findByMid(@Param("mid") String mid, Sort sort);

推荐方案 #

最简洁且可靠的是第一种方案，显式指定JPQL的countQuery，既避免了原生查询，又直接解决了找不到命名查询的异常，无需额外的命名查询配置。

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