Java 后端 / 系统课时
实现分页、排序与动态条件
实现分页、排序与动态条件
本课把列表查询拆成三个职责:Pageable 控制页码和每页数量,Sort 决定稳定顺序,Specification 按请求参数动态拼接条件。完成后,你可以用一个接口同时支持分页、排序和可选筛选,并避免把大量条件判断堆进 Repository 方法名。
学习目标
- 使用
Pageable和Sort构造稳定、可复现的分页查询 - 使用
Specification按需组合字符串、枚举和时间条件 - 识别分页越界、排序字段注入和模糊查询转义等边界
查询职责如何分工
分页、排序和筛选解决的是三类不同问题。Pageable 描述“取哪一页”,Sort 描述“先按什么排列”,Specification 描述“哪些记录可以进入结果集”。三者最终由 Spring Data JPA 合并成一条带 where、order by、limit 和 offset 的查询。

分页必须建立稳定排序。只按可能重复的 createdAt 排序时,同一时刻创建的记录在不同查询中可能交换位置,因此通常再追加唯一键 id 作为次级排序条件。
定义实体与 Repository
下面是项目片段示例,依赖已有的 Spring Boot 3、Spring Data JPA 和数据库配置。Repository 同时继承 JpaRepository 与 JpaSpecificationExecutor,前者提供基础 CRUD,后者提供 Specification 查询入口。
package com.example.user;
import jakarta.persistence.*;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
import java.time.Instant;
@Entity
@Table(name = "app_user")
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, length = 64)
private String username;
@Enumerated(EnumType.STRING)
@Column(nullable = false, length = 20)
private UserStatus status;
@Column(nullable = false)
private Instant createdAt;
protected User() {
}
public Long getId() {
return id;
}
public String getUsername() {
return username;
}
public UserStatus getStatus() {
return status;
}
public Instant getCreatedAt() {
return createdAt;
}
}
enum UserStatus {
ACTIVE, DISABLED
}
interface UserRepository extends JpaRepository<User, Long>,
JpaSpecificationExecutor<User> {
}这段代码生效后,userRepository.findAll(specification, pageable) 会同时应用动态条件和分页参数。验证方式是在下一节调用查询接口,并检查返回的 totalElements、totalPages 和 content。
组合动态筛选条件
将条件构造集中到一个规格类中,可以避免 Controller 直接操作 Criteria API。每个请求参数为空时返回 null,Spring Data JPA 会忽略该条件;有值时再生成对应谓词。
package com.example.user;
import org.springframework.data.jpa.domain.Specification;
import java.time.Instant;
public final class UserSpecifications {
private UserSpecifications() {
}
public static Specification<User> usernameContains(String keyword) {
return (root, query, cb) -> {
if (keyword == null || keyword.isBlank()) {
return null;
}
String escaped = keyword.trim()
.replace("\\", "\\\\")
.replace("%", "\\%")
.replace("_", "\\_");
return cb.like(
cb.lower(root.get("username")),
"%" + escaped.toLowerCase() + "%",
'\\'
);
};
}
public static Specification<User> hasStatus(UserStatus status) {
return (root, query, cb) ->
status == null ? null : cb.equal(root.get("status"), status);
}
public static Specification<User> createdAtOrAfter(Instant createdFrom) {
return (root, query, cb) ->
createdFrom == null
? null
: cb.greaterThanOrEqualTo(root.get("createdAt"), createdFrom);
}
}这里显式转义 % 和 _,防止用户输入被当成 SQL LIKE 通配符。字段名使用实体属性名,而不是数据库列名;如果属性重命名,字符串路径也必须同步修改。
构造安全的分页查询
排序字段不能直接信任客户端输入,否则非法字段会在运行时触发异常。更稳妥的做法是建立白名单映射,并限制最大页大小。
package com.example.user;
import org.springframework.data.domain.*;
import org.springframework.data.jpa.domain.Specification;
import org.springframework.stereotype.Service;
import java.time.Instant;
import java.util.Map;
@Service
public class UserQueryService {
private static final int MAX_PAGE_SIZE = 100;
private static final Map<String, String> SORT_FIELDS = Map.of(
"id", "id",
"username", "username",
"createdAt", "createdAt"
);
private final UserRepository userRepository;
public UserQueryService(UserRepository userRepository) {
this.userRepository = userRepository;
}
public Page<User> search(
int page,
int size,
String sortBy,
Sort.Direction direction,
String keyword,
UserStatus status,
Instant createdFrom
) {
int safePage = Math.max(page, 0);
int safeSize = Math.min(Math.max(size, 1), MAX_PAGE_SIZE);
String property = SORT_FIELDS.getOrDefault(sortBy, "createdAt");
Sort sort = Sort.by(direction, property)
.and(Sort.by(Sort.Direction.DESC, "id"));
Pageable pageable = PageRequest.of(safePage, safeSize, sort);
Specification<User> specification = Specification
.where(UserSpecifications.usernameContains(keyword))
.and(UserSpecifications.hasStatus(status))
.and(UserSpecifications.createdAtOrAfter(createdFrom));
return userRepository.findAll(specification, pageable);
}
}当 page 小于 0 时归零,size 被限制在 1~100,未知排序字段回退到 createdAt。若业务要求非法参数直接返回 400,可把归一化改为 Bean Validation 校验,但不要悄悄接受无限大的 size。
暴露接口并验证结果
Controller 只负责接收参数和调用服务。下面给出可执行的 HTTP 请求示例,假设应用运行在 <PORT>,实际端口可能不同。
package com.example.user;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Sort;
import org.springframework.format.annotation.DateTimeFormat;
import org.springframework.web.bind.annotation.*;
import java.time.Instant;
@RestController
@RequestMapping("/api/users")
public class UserQueryController {
private final UserQueryService userQueryService;
public UserQueryController(UserQueryService userQueryService) {
this.userQueryService = userQueryService;
}
@GetMapping
public Page<User> search(
@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "20") int size,
@RequestParam(defaultValue = "createdAt") String sortBy,
@RequestParam(defaultValue = "DESC") Sort.Direction direction,
@RequestParam(required = false) String keyword,
@RequestParam(required = false) UserStatus status,
@RequestParam(required = false)
@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)
Instant createdFrom
) {
return userQueryService.search(
page, size, sortBy, direction, keyword, status, createdFrom
);
}
}curl "http://localhost:<PORT>/api/users?page=0&size=2&sortBy=createdAt&direction=DESC&keyword=ali&status=ACTIVE"预期结果
{
"content": [
{
"id": 12,
"username": "alice",
"status": "ACTIVE",
"createdAt": "2026-08-06T10:00:00Z"
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 2
},
"totalElements": 1,
"totalPages": 1,
"first": true,
"last": true,
"number": 0,
"size": 2,
"numberOfElements": 1,
"empty": false
}实际 JSON 可能包含更多分页元数据,记录 ID 和时间也会不同。验收时重点确认筛选条件生效、结果顺序稳定、页大小未超过上限,并检查请求不存在匹配记录时 content 为空而不是报错。
关键边界
页码从 0 开始;请求第 1 页应传 page=0。深分页会让数据库扫描和丢弃大量记录,当页码非常大时应考虑基于游标或最后一条排序键的 Keyset Pagination。
动态条件越多,越要关注索引。常见组合是给高选择性的等值条件和稳定排序字段建立联合索引,但索引顺序应根据真实查询与执行计划决定,不能仅按代码中的条件顺序照搬。