Spring @Query未配置Pageable参数及相关异常排查

我之前在Spring Data JPA开发中也踩过类似的分页查询坑，结合你描述的情况，咱们一步步拆解问题根源：

首先说你最初的问题：把PageRequest作为第二个参数引发异常 #

Spring Data JPA对分页查询的Pageable参数有两个关键要求：

• 参数类型必须是**Pageable接口**，而不是具体的PageRequest实现类（Spring需要通过接口做动态代理处理分页逻辑）
• Pageable参数必须放在方法参数的最后一位，不能插在中间

比如错误写法：

// 错误：用了PageRequest实现类，且位置不对
@Query("SELECT u FROM User u WHERE u.status = ?1")
Page<User> findUsers(String status, PageRequest pageable);

正确的写法应该是：

// 正确：用Pageable接口，且放在最后
@Query("SELECT u FROM User u WHERE u.status = ?1")
Page<User> findUsers(String status, Pageable pageable);

调用的时候再传入PageRequest.of(0, 10)这类实例就可以了。

然后是移除参数后仍报错，错误位置变化的问题 #

这说明你移除Pageable参数后，暴露了原来@Query语句里的另一个问题：参数占位符和方法参数不匹配。

举个例子，假设你原来的代码是这样的：

// 错误示例
@Query("SELECT u FROM User u WHERE u.status = ?1 AND u.level > ?2")
Page<User> findUsers(String status, PageRequest pageable);

这里JPQL里用了?2，但你把PageRequest作为第二个参数，它根本不是level对应的数值参数，所以会报错。当你移除PageRequest后，方法只剩下一个参数，但JPQL里还留着?2，这时候错误就会指向?1或者提示参数数量不足，也就是你说的“错误指向从#2变为#1”。

给你的排查和修复步骤 #

1. 修正Pageable参数的写法：确保参数类型是Pageable，且放在方法参数末尾
2. 检查JPQL的参数绑定：
   • 位置参数（?1、?2）要和方法参数的顺序、数量完全对应
   • 更推荐用命名参数代替位置参数，这样不容易搞混顺序，比如：

     @Query("SELECT u FROM User u WHERE u.status = :status")
     Page<User> findActiveUsers(@Param("status") String status, Pageable pageable);
     

3. 移除参数后报错的话：检查JPQL里有没有多余的占位符，比如原来的?2现在没有对应的参数，要删掉或者补充对应的方法参数

按照这个思路调整，应该就能解决你遇到的两个问题了。

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