Java 后端 / 系统课时

实现分页、排序与动态条件

实现分页、排序与动态条件

本课把列表查询拆成三个职责:Pageable 控制页码和每页数量,Sort 决定稳定顺序,Specification 按请求参数动态拼接条件。完成后,你可以用一个接口同时支持分页、排序和可选筛选,并避免把大量条件判断堆进 Repository 方法名。

学习目标

  • 使用 Pageable 和 Sort 构造稳定、可复现的分页查询
  • 使用 Specification 按需组合字符串、枚举和时间条件
  • 识别分页越界、排序字段注入和模糊查询转义等边界

查询职责如何分工

分页、排序和筛选解决的是三类不同问题。Pageable 描述“取哪一页”,Sort 描述“先按什么排列”,Specification 描述“哪些记录可以进入结果集”。三者最终由 Spring Data JPA 合并成一条带 where、order by、limit 和 offset 的查询。

Pageable、Sort 与 Specification 协作流程

分页必须建立稳定排序。只按可能重复的 createdAt 排序时,同一时刻创建的记录在不同查询中可能交换位置,因此通常再追加唯一键 id 作为次级排序条件。

定义实体与 Repository

下面是项目片段示例,依赖已有的 Spring Boot 3、Spring Data JPA 和数据库配置。Repository 同时继承 JpaRepository 与 JpaSpecificationExecutor,前者提供基础 CRUD,后者提供 Specification 查询入口。

java
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 会忽略该条件;有值时再生成对应谓词。

java
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 通配符。字段名使用实体属性名,而不是数据库列名;如果属性重命名,字符串路径也必须同步修改。

构造安全的分页查询

排序字段不能直接信任客户端输入,否则非法字段会在运行时触发异常。更稳妥的做法是建立白名单映射,并限制最大页大小。

java
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>,实际端口可能不同。

java
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
        );
    }
}
bash
curl "http://localhost:<PORT>/api/users?page=0&size=2&sortBy=createdAt&direction=DESC&keyword=ali&status=ACTIVE"

预期结果

json
{
  "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。

动态条件越多,越要关注索引。常见组合是给高选择性的等值条件和稳定排序字段建立联合索引,但索引顺序应根据真实查询与执行计划决定,不能仅按代码中的条件顺序照搬。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现分页、排序与动态条件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通