Spring JPA自定义查询分页异常：仅特定场景可用求助

嘿，我碰到过类似的分页坑，给你梳理几个最可能的问题点，你可以挨个排查：

1. 自定义SQL的分页逻辑没处理对 #

如果你的自定义查询用了原生SQL（nativeQuery=true），Spring Data JPA不会自动帮你拼接分页语句，得自己在SQL里加上对应数据库的分页语法，比如MySQL的LIMIT ? OFFSET ?，或者PostgreSQL的LIMIT ? OFFSET ?。如果没加这部分，只有当请求的页码刚好匹配默认的分页参数时才会“巧合”正常，其他情况就会失效。

举个修正后的例子（MySQL）：

@Repository
public interface SmsLogRepository extends JpaRepository<SmsLog, Long> {
    // 显式指定分页语法，参数顺序对应分页偏移量和每页条数
    @Query(value = "select * from sms_log where your_condition_here LIMIT ?2 OFFSET ?1", 
           countQuery = "select count(*) from sms_log where your_condition_here",
           nativeQuery = true)
    Page<SmsLog> findCustomSmsLogs(int offset, int pageSize);
}

或者更优雅的方式，直接把Pageable作为参数，让JPA自动拼接分页语句（Spring Data JPA 2.x+支持原生SQL自动处理分页）：

@Repository
public interface SmsLogRepository extends JpaRepository<SmsLog, Long> {
    @Query(value = "select * from sms_log where your_condition_here", 
           countQuery = "select count(*) from sms_log where your_condition_here",
           nativeQuery = true)
    Page<SmsLog> findCustomSmsLogs(Pageable pageable);
}

2. 页码的索引搞混了 #

Spring Data JPA的Pageable默认是从0开始计数的，但很多前端系统的页码是从1开始的。你提到的场景：数据量少于10条时页码0正常，数据量多于10条时页码1正常，大概率是页码转换出了问题——比如前端传1的时候你直接用了，刚好对应JPA的第0页？或者反过来？

解决方法是统一页码索引：如果前端传的是从1开始的页码，转成JPA需要的0开始：

// 假设前端传来的pageNum是1
int jpaPageNum = pageNum - 1;
Pageable pageable = PageRequest.of(jpaPageNum, 10); // pageSize设为10

3. 缺少正确的count查询 #

分页需要知道总数据条数来计算总页数、是否有下一页等信息。如果你的自定义查询没有指定countQuery，JPA可能会自动生成count语句，但自动生成的语句有时候会因为复杂过滤条件出错，导致分页逻辑异常。

所以一定要显式指定countQuery，确保它和主查询的过滤条件完全一致，比如上面代码示例里的countQuery部分。

4. 开启SQL日志看实际执行语句 #

最直接的方法是开启Spring的SQL日志，看看实际执行的SQL里的分页参数（OFFSET和LIMIT）是不是符合预期。比如在application.properties里加：

spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

这样就能看到执行的SQL语句，检查OFFSET的值是不是正确——比如请求页码2的时候，OFFSET是不是20（假设pageSize是10），如果不是，那就是页码转换或者参数传递的问题。

按照这几个步骤排查，应该能找到问题所在～

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