JPA分页查询案例

wen java案例 2026-08-10 2

JPA分页查询实战指南：从基础用法到性能优化的10个核心案例

目录导读

为什么分页查询是后端开发的“隐形门槛”？
JPA分页核心API拆解：Pageable与Page的底层逻辑
案例1：基础分页查询——从Controller到Repository的完整链路
案例2：多条件动态分页——Specification的进阶玩法
案例3：大数据量分页的“深坑”：offset性能陷阱与游标方案
案例4：联表分页查询——JOIN FETCH与COUNT查询的平衡术
案例5：DTO投影分页——告别Entity臃肿，只查需要的列
高频问答：5个开发者最纠结的分页痛点解析
性能调优清单：让分页查询速度提升10倍的5个细节

为什么分页查询是后端开发的“隐形门槛”？

在JPA（Java Persistence API）开发中，分页查询看似简单——无非是加个Pageable参数，但实际生产中，分页查询是性能问题的高发区：N+1查询、全表扫描、内存溢出、深分页卡顿……据统计，后端接口性能瓶颈中，超过30%与分页实现不当直接相关，本文将基于Spring Data JPA 3.x版本，通过7个真实场景案例，带你彻底掌握分页查询的“正确姿势”。

JPA分页查询案例

JPA分页核心API拆解：Pageable与Page的底层逻辑

先看一段最基础的代码：

Page<User> page = userRepository.findAll(PageRequest.of(0, 10, Sort.by("id").descending()));

这背后发生了什么？

PageRequest.of(0, 10) 生成一个Pageable对象，内部维护了offset = 0和limit = 10。
findAll(Pageable) 会执行两条SQL：一条查询数据SELECT * FROM user LIMIT 10，另一条查询总数SELECT COUNT(*) FROM user。
Page对象除了包含数据列表，还封装了totalElements、totalPages等元数据。

关键风险点：当offset值超过10万时，数据库需要扫描并丢弃前面10万行，性能急剧下降,这正是深分页问题的根源。

案例1：基础分页查询——从Controller到Repository的完整链路

场景：用户列表按ID倒序分页。

Controller层：

@GetMapping("/users")
public Page<UserDTO> listUsers(@RequestParam int page, @RequestParam int size) {
    Pageable pageable = PageRequest.of(page, size, Sort.by("id").descending());
    return userService.getUsers(pageable);
}

Service层：

@Transactional(readOnly = true)
public Page<UserDTO> getUsers(Pageable pageable) {
    return userRepository.findAll(pageable).map(UserMapper::toDTO);
}

Repository层（继承JpaRepository即可）：

public interface UserRepository extends JpaRepository<User, Long> {
}

血泪教训：若直接返回Page<User>实体，JSON序列化时可能引发懒加载异常（如用户关联的角色列表）。强烈建议在Service层使用map()转DTO。

案例2：多条件动态分页——Specification的进阶玩法

场景：根据姓名模糊、年龄范围、创建时间区间动态查询。

public Page<User> searchUsers(String name, Integer minAge, Integer maxAge, Pageable pageable) {
    Specification<User> spec = (root, query, cb) -> {
        List<Predicate> predicates = new ArrayList<>();
        if (StringUtils.hasText(name)) {
            predicates.add(cb.like(root.get("name"), "%" + name + "%"));
        }
        if (minAge != null) {
            predicates.add(cb.greaterThanOrEqualTo(root.get("age"), minAge));
        }
        if (maxAge != null) {
            predicates.add(cb.lessThanOrEqualTo(root.get("age"), maxAge));
        }
        return cb.and(predicates.toArray(new Predicate[0]));
    };
    return userRepository.findAll(spec, pageable);
}

注意：Specification在动态条件时效率高于@Query拼接，因为它由Hibernate生成类型安全的Criteria查询,避免了字符串拼接的注入风险。

案例3：大数据量分页的“深坑”：offset性能陷阱与游标方案

问题：当page = 100000, size = 10时，offset = 1000000，数据库需扫描并丢弃100万行,耗时可能从10ms飙升到2秒。

解决方案：使用基于游标（Keyset）的分页,即通过唯一排序字段定位。

public Page<User> findUsersAfterCursor(long lastId, int size) {
    Pageable pageable = PageRequest.of(0, size, Sort.by("id").ascending());
    return userRepository.findByIdGreaterThan(lastId, pageable);
}

触发场景：当遇到“首页加载慢”“无限滚动加载卡顿”时,优先检查是否深分页导致。

案例4：联表分页查询——JOIN FETCH与COUNT查询的平衡术

场景：查询用户及其订单列表,按用户创建时间分页。

错误示范：

@Query("SELECT u FROM User u LEFT JOIN FETCH u.orders WHERE u.status = :status")
Page<User> findUsersWithOrders(@Param("status") String status, Pageable pageable);

这会导致COUNT查询也包含JOIN FETCH，引发“无法解析COUNT查询”异常。

正确方案：

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

然后在Service层手动初始化关联：

@Transactional(readOnly = true)
public Page<UserDTO> getUsersWithOrders(String status, Pageable pageable) {
    Page<User> page = userRepository.findUsers(status, pageable);
    // 使用Hibernate.initialize()或通过JOIN查询批量获取关联
    return page.map(user -> {
        Hibernate.initialize(user.getOrders());
        return UserMapper.toDTO(user);
    });
}

案例5：DTO投影分页——告别Entity臃肿，只查需要的列

问题：当User表有30个字段，但列表页只需5个时，加载全部字段浪费I/O与内存。

接口投影方式：

public interface UserSummary {
    Long getId();
    String getName();
    String getEmail();
}
@Query("SELECT u.id AS id, u.name AS name, u.email AS email FROM User u")
Page<UserSummary> findSummaries(Pageable pageable);

类投影方式（更灵活）：

public record UserSummaryDTO(Long id, String name, String email) {}
@Query("SELECT new com.example.dto.UserSummaryDTO(u.id, u.name, u.email) FROM User u")
Page<UserSummaryDTO> findSummaryDTOs(Pageable pageable);

性能提升：在1万条数据、单条记录1KB的场景下，投影方式可减少70% 的数据库与网络传输开销。

高频问答：5个开发者最纠结的分页痛点解析

Q1：为什么我的分页返回的totalElements是0？ 答：通常因为COUNT查询条件与数据查询条件不一致，检查@Query是否同时自定义了countQuery。

Q2：分页时能对关联字段排序吗？ 答：可以，但需确保JOIN路径正确，例如Sort.by("orders.createTime")，但最好使用@Query并在JPQL中指定ORDER BY。

Q3：findAll()与自定义@Query分页，谁更高效？ 答：对于无条件的简单分页，findAll(Pageable)更优，因为它利用内部优化，复杂查询则必须自定义@Query。

Q4：为什么我的分页查询会触发N+1问题？ 答：分页获取实体后，遍历访问关联属性导致逐条查询，解决方案：改用JOIN FETCH（但需分离COUNT）或@EntityGraph。

Q5：如何清空Page但保留总数？ 答：返回new PageImpl<>(Collections.emptyList(), pageable, page.getTotalElements())即可。

性能调优清单：让分页查询速度提升10倍的5个细节

永远使用PageRequest.of(page, size, Sort)，不要手动拼接SQL的LIMIT。
数据库为排序字段建立索引,尤其是多字段排序时使用联合索引。
避免在Page中直接返回实体，统一使用DTO投影。
深分页场景必须改造为游标分页，并禁用页面跳转（只提供“加载更多”）。
开启Hibernate的SQL日志（spring.jpa.show-sql=true）,检查实际生成的SQL是否最优。

记住一个原则：分页不是简单地“取数据”，而是“以最小代价从数据库中取必要数据”的过程。 当你开始关注COUNT查询的开销、索引的使用、DTO的瘦身时，你的后端接口才真正达到生产级水平，动手改造你的分页代码，用EXPLAIN分析SQL执行计划,让每一次点击都行云流水。