Spring Data JPA百万级数据分页查询与性能优化实战

做本地生活平台的营销后端时，霸王餐是拉新促活的常用玩法：用户报名参与活动，到店核销后获得免单或减免权益。活动一铺开，参与记录的增长速度非常快，单日几十万条写入属于常态，后台运营隔三差五就要拉数看效果。我刚接手这个模块时，第一个被反复问到的需求就是"帮我导一下上周参与A活动且已核销的用户清单"，第二个是"某个商户下所有待核销的报名记录分页看一下"。拆开看都是同一个技术问题：如何用Spring Data JPA在百万级数据量的参与记录上实现高效的分页与条件查询。这篇文章整理了我从接口设计到落地排查的完整过程，适合正在用JPA做后台管理系统的Java开发者，也适合从MyBatis迁移过来、对JPA查询方式不够熟悉的朋友对照参考。

1. 霸王餐活动记录的业务特点与查询需求拆解

1.1 参与记录表的数据画像

先看业务表。霸王餐参与记录的核心字段不外乎这些：用户ID、活动ID、商户ID、参与状态、核销时间、创建时间。状态一般分待核销、已核销、已取消几档。

这种表有几个鲜明特点：第一，写入基本只增不改，核销只在极短时间内发生一次更新；第二，单活动数据峰值明显，一个爆款活动可能在一周内产生数十万条记录；第三，运营查询条件组合非常多，有时候按活动筛，有时候按商户筛，有时候按时间段筛，还有时候几个条件一起来。

我当时先做了实体设计，索引都建在业务查询路径上：

@Entity @Table(name = "feast_participation", indexes = { @Index(name = "idx_activity_status_time", columnList = "activity_id,status,create_time"), @Index(name = "idx_user_create_time", columnList = "user_id,create_time"), @Index(name = "idx_merchant_status", columnList = "merchant_id,status") }) public class FeastParticipation { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(name = "user_id", nullable = false) private Long userId; @Column(name = "activity_id", nullable = false) private Long activityId; @Column(name = "merchant_id", nullable = false) private Long merchantId; @Column(name = "status", nullable = false) private Integer status; @Column(name = "verify_time") private LocalDateTime verifyTime; @Column(name = "create_time", nullable = false, updatable = false) private LocalDateTime createTime; }

索引设计是很多人忽略但极其关键的一步。JPA分页查询最后落到数据库还是SQL，索引不在，SQL再优雅也白搭。这里我把status和create_time都放在联合索引里，就是为了让"按活动+状态+时间倒序"这条最频繁的查询路径能走索引覆盖，避免回表排序。

1.2 查询需求的本质拆解

运营侧和业务侧的需求看着五花八门，归纳下来无非三点：

• 条件组合不固定：今天筛"活动A+已核销"，明天筛"商户B+待核销+本周"，后天可能就是"用户C的全部记录"
• 分页深度大：运营习惯翻页，动辄翻到几十上百页
• 列表要带关联信息：光显示user_id不够，还要用户昵称、活动名称

这三点分别决定了技术选型的三个方向：条件组合要用动态查询，不能写死；分页要能支撑深度翻页且性能可控；关联信息要防N+1。后续章节的每一段代码，本质上都是围绕这三个点展开的。

这里顺便解释一个很多人问过我的问题：为什么条件查询用动态Specification而不是JPQL字符串拼接？因为JPQL字符串拼接容易出错且不易维护，而Specification是基于Criteria API的类型安全封装，条件是可以组合的"谓词"对象，在编译期就能帮你检查字段名错误。具体代码在第三章给出。

2. 分页查询的第一层选择：JPA三种查询姿势怎么搭

2.1 派生查询：最省事，但别当万能药

Spring Data JPA的接口派生查询是我最先使用的方式，因为它几乎零成本。只要方法名按规则写，分页就自动完成：

public interface FeastParticipationRepository extends JpaRepository<FeastParticipation, Long> { Page<FeastParticipation> findByActivityIdAndStatus( Long activityId, Integer status, Pageable pageable); Page<FeastParticipation> findByUserIdAndCreateTimeBetween( Long userId, LocalDateTime start, LocalDateTime end, Pageable pageable); }

调用方只需要构造Pageable：

Pageable pageable = PageRequest.of(0, 10, Sort.by(Sort.Direction.DESC, "createTime")); Page<FeastParticipation> page = repository.findByActivityIdAndStatus(101L, 1, pageable);

这一套下来，Spring Data JPA会帮我们自动生成两条SQL：一条count统计总条数，一条limit查询当前页数据。方法名本身就成了文档，谁来看都知道这个查询干什么。

但它的问题也很明显：条件一旦多起来，方法名会变得又臭又长。试想一下"findByActivityIdAndStatusAndUserIdAndCreateTimeBetweenAndMerchantIdIn"这种签名，看着就崩溃，而且每个新条件都要新增方法，根本维护不过来。所以我的经验是：固定条件在三四个以内的简单分页，用派生查询很合适；条件稍多，立刻切换方案。

2.2 @Query注解：灵活性与可控性之间的平衡

当派生查询撑不住，又不想直接上原生SQL，@Query注解是最常用的升级手段。它有两种写法：JPQL和原生SQL。

先看JPQL方式的典型写法：

@Query("select p from FeastParticipation p " + "where p.activityId = :activityId and p.status = :status") Page<FeastParticipation> queryByActivityAndStatus( @Param("activityId") Long activityId, @Param("status") Integer status, Pageable pageable);

这里有个很重要的经验：如果参数可能为null，使用JPA的SpEl表达式按需拼接，但这属于动态查询的范畴，我在第三章专门讲。当查询条件相对固定、只是需要连表或者写一些派生查询表达不了的逻辑时，@Query是首选。它保留了JPQL的类型检查和可读性，比原生SQL更安全。

2.3 原生SQL：什么时候才需要下探到这一层

原生SQL通常在三种情况下才值得用：需要调用数据库专有函数（比如MySQL的DATE_FORMAT、JSON_EXTRACT）；需要针对特定数据库做锁或强制索引；需要实现深度分页优化这类与数据库物理执行计划强相关的逻辑。

举个真实的例子：运营要求按天展示参与人数趋势，这个在JPQL里写group by date(create_time)语法上可行，但可读性和性能都比较差，用SQL直接写更直观。还有一个场景就是第四章的游标分页，它本质上依赖SQL的where order by limit，必须用原生SQL或JPQL的底层写法才能实现。

但原生SQL有个硬伤：返回的数据类型变成了Object[]或者数据库原生类型，丧失了JPA的实体映射能力。即使用了Projection接口，也只是半映射。所以我的原则是：能用JPQL解决的绝不用原生SQL，只有确确实实需要数据库特性时再下探。

三种方式的取舍可以总结为一张表：

3. 动态条件查询的核心：Specification的正确打开方式

3.1 Specification机制的原理

运营的筛选条件永远是动态的，这意味着查询条件数量、哪些条件生效，都得在运行时决定。JPA为此提供的标准方案是Specification，它是对Criteria API的封装。

Criteria API的工作方式可以这样理解：你不是写一条完整的SQL，而是通过JPA的Builder对象一点点"搭建"条件。每个条件都是一个Predicate（谓词），你可以把它们组合、取反、连接。Specification只是把这一套逻辑包装成一个可复用的函数：

public interface Specification<T> { Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, CriteriaBuilder cb); }

你只需要实现这个函数，把"当xxx条件成立时，往predicates里加一个条件"这件事表达清楚，剩下的交给JPA。编译期就能发现字段名写错的低级问题，而且可以随意组合，这是JPQL字符串拼接完全比不上的。

Repository要支持Specification，需要额外继承一个接口：

public interface FeastParticipationRepository extends JpaRepository<FeastParticipation, Long>, JpaSpecificationExecutor<FeastParticipation> { }

继承之后，repository自动获得一组以Specification为入参的查询方法，包括findAll(Specification, Pageable)、count(Specification)等。配合Pageable就是分页条件查询的完全体。

3.2 一个支持多条件组合的通用封装

实际项目中我不会直接写一堆Specification匿名类散落在Service里，而是把所有筛选逻辑收敛到一个查询对象和对应的Specification工厂中。

先定义查询入参：

public class ParticipationQuery { private Long userId; private Long activityId; private Long merchantId; private Integer status; private LocalDateTime startTime; private LocalDateTime endTime; private Integer pageNum = 0; private Integer pageSize = 10; private String sortField = "createTime"; private String sortOrder = "desc"; // 省略getter/setter }

再建Specification工厂：

public class ParticipationSpecs { public static Specification<FeastParticipation> buildWhere(ParticipationQuery query) { return (root, cq, cb) -> { List<Predicate> predicates = new ArrayList<>(); if (query.getUserId() != null) { predicates.add(cb.equal(root.get("userId"), query.getUserId())); } if (query.getActivityId() != null) { predicates.add(cb.equal(root.get("activityId"), query.getActivityId())); } if (query.getMerchantId() != null) { predicates.add(cb.equal(root.get("merchantId"), query.getMerchantId())); } if (query.getStatus() != null) { predicates.add(cb.equal(root.get("status"), query.getStatus())); } if (query.getStartTime() != null) { predicates.add(cb.greaterThanOrEqualTo(root.get("createTime"), query.getStartTime())); } if (query.getEndTime() != null) { predicates.add(cb.lessThanOrEqualTo(root.get("createTime"), query.getEndTime())); } return cb.and(predicates.toArray(new Predicate[0])); }; } }

Service里的调用就非常清爽：

Page<FeastParticipation> page = repository.findAll( ParticipationSpecs.buildWhere(query), PageRequest.of(query.getPageNum(), query.getPageSize(), buildSort(query)) );

我特别喜欢这个封装的原因是：新增一个筛选条件，只需要改两个地方——Query对象加字段、Specification工厂加一个if判断。其他所有地方零改动。运营后来要求加"按核销时间范围筛选"，我五分钟就上线了。

3.3 时间范围、模糊匹配与In条件的处理细节

条件查询不只是等值匹配，实际中会遇到更多类型。

时间范围上面已经写了：用greaterThanOrEqualTo和lessThanOrEqualTo两个谓词夹一个Between效果。需要注意的是时间边界，如果endTime是"2025-01-31"，直接用lessThanOrEqualTo会漏掉当天23:59:59之后的数据，常见做法是endTime统一加一天或者直接用lessThan(exclusiveEndTime)，exclusiveEndTime = endTime.plusDays(1)。我把这个写进了团队规范里。

模糊匹配要用criteriaBuilder.like，配合"%"通配符：

if (StringUtils.hasText(query.getUserNickname())) { predicates.add(cb.like(root.get("user").get("nickname"), "%" + query.getUserNickname() + "%")); }

这里有个坑。如果FeastParticipation关联了UserInfo，写root.get("user").get("nickname")时，JPA会隐式创建inner join，如果查询里只有一个关联字段还好，一旦多个关联字段都这样访问，就会产生多个join，性能风险不小。我自己处理这种场景时，更倾向于不关联查昵称，而是先查出分页记录，再批量查用户信息填充到VO。这一点第四节会说。

In条件用root.get("status").in(statusList)，配合集合入参。注意空集合要提前判断，否则生成的SQL是in ()，这在MySQL里是语法错误，H2里可能会直接报错。

4. 高性能分页的底层优化：从count到深分页

4.1 count查询的隐性开销与优化

很多人没意识到，JPA分页查询自动执行的那条count，在高并发大表场景下可能是性能杀手。怎么排查？打开SQL日志，你会发现Spring Data JPA默认生成的count语句通常长这样：

select count(p.id) from feast_participation p where p.activity_id = ? and p.status = ?

这条SQL在普通场景下没问题，但一旦查询条件里带了关联表的过滤或者复杂子查询，count的执行成本直线上升。更麻烦的是，有的团队用@Query写了很复杂的主查询，却忘了单独指定countQuery，Spring Data JPA会把整个复杂查询包装成count，性能极差。

解决办法是在@Query里显式指定countQuery：

@Query(value = "select p from FeastParticipation p join fetch p.userInfo " + "where p.activityId = :activityId", countQuery = "select count(p.id) from FeastParticipation p where p.activityId = :activityId") Page<FeastParticipation> findByActivityWithUser(Long activityId, Pageable pageable);

countQuery可以比主查询简单得多，只要保证过滤条件一致即可，关联fetch全部去掉。这一步优化往往能让列表接口的整体耗时下降一个量级。

还有一个小技巧：如果业务方根本不关心总数，只关心"有没有下一页"，可以自定义Pageable返回Page但把total设为0，或者干脆用Slice代替Page。Slice不执行count查询，只多查一条判断是否还有下一个。Spring Data JPA对返回Slice的方法不会做count，这个特性适合无限滚动的移动端列表。

4.2 大偏移量分页的三种改造方案

分页查询有个物理现实：offset越大，数据库扫描和丢弃的行越多。翻到100页时，limit 10 offset 990这条SQL，MySQL大概要扫描1000多行然后扔掉990行，索引再完美也救不了这个开销。

我遇到的真实案例，某个运营导出明细，一页100条，翻到第50页时接口已经要跑两三秒。要解决深分页，有三种主流改造方案。

第一种是游标分页（也称keyset分页）。核心思想是用"上一页最后一条记录"的排序字段值作为下一页的起点，完全抛弃offset。在JPA里可以这样写：

@Query("select p from FeastParticipation p " + "where p.createTime < :cursorTime " + "and (:userId is null or p.userId = :userId) " + "order by p.createTime desc") List<FeastParticipation> fetchPageAfterCursor( @Param("cursorTime") LocalDateTime cursorTime, @Param("userId") Long userId, Pageable pageable);

Service层这样调用：

int pageSize = query.getPageSize(); List<FeastParticipation> list = repository.fetchPageAfterCursor( lastCreateTime, userId, PageRequest.of(0, pageSize + 1)); boolean hasNext = list.size() > pageSize; if (hasNext) { list = list.subList(0, pageSize); }

游标分页的查询复杂度从O(offset)降到了O(log n)，翻得越深收益越大。代价是放弃了随机跳页，只能一页页往后翻，刚好符合运营端"按时间排序逐页核对"的习惯。

第二种是延迟关联。先只查主表主键ID，再回表取完整数据：

@Query("select p.id from FeastParticipation p " + "where p.activityId = :activityId order by p.createTime desc") Page<Long> findIdsByActivity(Long activityId, Pageable pageable);

拿到ID后，再通过IN查询一次性关联出完整实体。由于ID主键查询本身效率极高，这种方案实现简单，跳页能力也保留，缺点是代码量多一些。

第三种是业务层限制。直接限定最大页码和单页大小，比如最多允许翻50页，超过就提示用导出功能。这不是技术方案，但往往是最快见效的方案，我在生产环境把pageSize上限从100调到了30之后，数据库压力肉眼可见地下降。

4.3 关联查询的N+1问题

分页列表要显示用户昵称、活动名称，这是刚需。但如果直接在循环里逐条getUserInfo().getNickname()，一条分页SQL加N次查询，就是经典的N+1。10条数据还好，100条就是101条SQL，页面必卡。

解决方式有两类。第一类是在Repository查询时用join fetch一次性拉出来：

@Query("select distinct p from FeastParticipation p " + "left join fetch p.userInfo " + "left join fetch p.activityInfo " + "where p.activityId = :activityId") Page<FeastParticipation> findWithAssociations(Long activityId, Pageable pageable);

注意两个细节：一是用left join fetch应对关联为空的情况；二是只能同时fetch多个单值关联（多对一、一对一），如果涉及集合关联（一对多），会产生笛卡尔积且分页count会异常，这种情况建议拆成两次查询。

第二类是批量填充。主查询不做任何关联，查出实体列表后，收集所有的userId然后一条select * from user_info where id in (...)批量取回，再在内存里组装VO。这种方式SQL总数恒定在个位数，且不受分页大小影响，是我在大流量接口里的首选。对应的VO转换逻辑也清晰，不会出现JPA代理对象序列化的坑（第五章节会讲）。

5. 我做这个功能时踩过的坑（实战排错记录）

5.1 排序字段被注入的隐患与白名单校验

上线后我收到过一条诡异的前端反馈：列表接口偶尔报错。看了日志发现是"Unknown column 'someField' in 'order clause'"。原因很简单，前端传来的sortField被直接拼进了Sort：

Sort.by(Sort.Direction.fromString(sortOrder), query.getSortField());

如果前端传了一个不存在的字段名，数据库就会报错。更麻烦的是，如果支持多字段排序且使用原生SQL，字段名拼接带来的SQL注入风险是真实存在的。虽然JPA的Sort生成的是参数化SQL，字段名仍然不能随意信任。

我的做法是维护一个排序白名单，只允许排序实体上已有的字段，而且做了别名映射：

private static final Map<String, String> SORT_FIELD_MAPPING = Map.of( "createTime", "createTime", "verifyTime", "verifyTime", "id", "id", "status", "status" ); public Sort buildSort(ParticipationQuery query) { String field = SORT_FIELD_MAPPING.get(query.getSortField()); if (field == null) { throw new IllegalArgumentException("不支持的排序字段: " + query.getSortField()); } Sort.Direction direction = "asc".equalsIgnoreCase(query.getSortOrder()) ? Sort.Direction.ASC : Sort.Direction.DESC; return Sort.by(direction, field); }

顺带说一句，排序方向如果前端传了奇怪的值，别直接报错，兜底成desc比较友好。这个白名单方法从上线到现在再没出过排序相关的线上问题。

5.2 Page返回值序列化后字段丢失的诡异问题

另一个让我排查了两个小时的坑：后端接口返回Page ，前端说拿不到total，content倒是有。原来问题出在Spring对接口的序列化上。Page本身是个接口，返回给前端时实际序列化的是它的动态代理或SimplePageImpl，前端拿到的是接口getter方法暴露出来的属性，而实际实现类的字段映射和接口不完全一致，导致某些JSON字段缺失或者结构不对。

解决办法是不要让Page对象直接暴露给前端，而是统一包装成自己的分页结果对象：

public class PageResult<T> { private List<T> content; private long total; private int pageNum; private int pageSize; private boolean hasNext; public static <T> PageResult<T> of(Page<T> page) { PageResult<T> result = new PageResult<>(); result.setContent(page.getContent()); result.setTotal(page.getTotalElements()); result.setPageNum(page.getNumber()); result.setPageSize(page.getSize()); result.setHasNext(page.hasNext()); return result; } }

这个封装还带来一个额外好处：你可以把关联信息放在content之前组装好，前端拿到的永远是干净且完整的结构。从那以后我所有分页接口统一返回PageResult，再没出过序列化问题。

5.3 与MyBatis-Plus分页的横向对比

做Java后端的团队不少在用MyBatis-Plus，关于"MyBatis-Plus分页失效"的讨论也很多。这类问题大部分出在配置上：分页插件（PaginationInnerInterceptor）没注册，或者版本不兼容导致拦截器不生效。你不写分页插件，Page参数传进去也是白传，SQL永远不会被改写。相比之下，Spring Data JPA的分页是框架内建的，只要Repository方法签名里声明了Pageable，它就会自动生成limit和count两条SQL，不存在"忘记配置导致分页失效"这个坑。

但JPA也有自己需要注意的边界。比如@Query里误用了join fetch再加上复杂countQuery，count可能去重错误；Sort排序方向字符串写错了也会直接抛异常。这些不是"失效"，是使用姿势的问题。理解了两个框架底层处理方式的不同——一个靠拦截器改SQL，一个靠代理和参数解析生成SQL——遇到问题时的排查路径会清晰很多。

6. 迁移到生产环境前，我建议你重点检查这几项

文章最后，把我上线这个功能前后所有检查项汇总一下。这些是我实际操作中反复确认后才敢上生产的结论，照着过一遍可以少踩很多雷。

第一，索引必须落在查询路径上。不管JPA写得再优雅，数据库层面没有对应索引，深分页和条件查询都会退化。建议开工前先模拟核心查询SQL，用explain看一遍。

第二，统一分页入参和返回结构。入参用一个ParticipationQuery对象，返回统一用PageResult，避免每个接口各写一套。前端联调省心，后端起新的列表功能也快。

第三，排序字段白名单、pageSize上限、最大页码限制，这三件事做在网关或者Service入口。不要依赖前端自觉。

第四，打开Hibernate SQL日志到生产观察几天。重点看有没有N+1查询、count语句是否走了合理的路径。Spring Boot里配置logging.level.org.hibernate.SQL=DEBUG即可，观察到问题及时改，别等线上反馈。

第五，深分页接口考虑游标方案或直接限制页码。导出功能单独走异步任务，不要占在线列表接口的数据库连接。

我个人体会最深的一点是：JPA分页功能本身足够成熟，真正决定系统表现的不是框架选型，而是你对底层SQL执行计划、索引和查询特性的理解。把"ORM帮你生成SQL"这件事拆开看透，很多问题都能在设计和代码阶段提前解决，而不是上线后让运营来帮你发现。