Spring Boot中使用@Query实现分页查询的最优JPA查询类型选择

首先直接给出结论：绝大多数业务场景下优先选择JPQL作为分页查询的实现方式，仅在特殊场景下考虑使用NativeQuery，具体对比逻辑如下：

优先选择JPQL的核心原因 #

• 分页逻辑原生适配，开发成本极低：Spring Data JPA对JPQL的Page返回类型做了原生支持，只需要在查询方法参数中传入Pageable对象，返回值声明为Page<T>，框架会自动生成对应的count统计查询，无需开发者手动编写总条数统计逻辑，开箱即可拿到包含总条数、总页数、当前页数据的完整分页对象

最简实现示例：

@Query("select u from User u where u.departmentId = :deptId")
Page<User> findByDeptId(Long deptId, Pageable pageable);

调用时直接传入PageRequest.of(页码, 每页条数)即可完成分页查询。

• 天然跨数据库兼容：JPQL是JPA定义的面向对象查询语言，底层会根据项目配置的数据库方言自动生成对应数据库的SQL，后续切换数据库（比如从MySQL迁移到PostgreSQL）时不需要修改查询代码
• 启动阶段语法校验：项目启动时Spring Data JPA会自动校验JPQL语法、实体字段映射是否正确，有问题会在启动阶段直接暴露，不会等到线上运行时才触发报错

适合选择NativeQuery的场景 #

仅当你需要用到数据库特有的语法特性（比如MySQL的窗口函数、JSON处理函数，或者复杂多表关联查询需要极致性能优化，JPQL生成的SQL无法满足要求）时，再选择NativeQuery实现分页，需要注意NativeQuery的分页坑：

• 必须手动指定count查询：NativeQuery默认不会自动生成总条数统计逻辑，需要在@Query注解中显式配置countQuery属性，否则分页功能会失效

正确实现示例：

@Query(value = "select * from user where department_id = :deptId", 
       countQuery = "select count(*) from user where department_id = :deptId",
       nativeQuery = true)
Page<User> findByDeptIdNative(Long deptId, Pageable pageable);

• 绑定具体数据库语法，不支持跨数据库兼容，切换数据库时需要同步修改SQL语句
• 没有启动时语法校验能力，SQL编写错误只有在接口调用时才会暴露，排查成本更高

最终选型建议 #

• 普通业务查询、未使用数据库特有能力的场景：直接选JPQL，开发效率最高、维护成本最低
• 复杂查询、必须依赖数据库特有语法、或JPQL生成的SQL性能无法达到要求的场景：再选择NativeQuery，注意手动配置countQuery属性

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