Spring Boot 统一分页参数手记:PageParam 与 PageResult 的实现与注意点

问题:每个列表接口都重写一遍分页

做后台管理系统时,几乎每个列表接口都要分页:用户列表、订单列表、日志列表。如果每个接口各自接收 pageNum、pageSize,各自算 offset、各自拼返回结构,很快就会出现三种不一致:有的接口 pageNum 从 0 开始,有的从 1 开始;有的允许 pageSize 传 10000,一次查爆内存;有的返回里只有 list 和 total,前端算总页数还要自己再算一遍。

适用的场景是常规的 Spring Boot 列表接口:管理后台分页查询、移动端下拉加载对应的分页接口、以及任何需要固定返回结构的 REST API。这篇手记给出一套可以直接复用的统一写法:一个 PageParam 收参数,一个 PageResult 统返回结构,校验、越界处理与排序白名单都收敛到这两处。

统一约定:先定下来,再写代码

  • 页码从 1 开始:pageNum 默认 1,最小 1,前端传 0 或负数时按 1 处理。
  • 每页条数默认 20,上限 100:pageSize 小于 1 时取默认值,大于 100 时截断为 100,避免一次返回全表数据。
  • 排序字段只认白名单:sortBy 不在白名单里时回落到 id,防止把任意字段拼进排序条件。
  • 返回结构固定五字段:list、total、pageNum、pageSize、pages,前端按同一结构解析所有列表接口。

PageParam:收参数、做校验、算偏移

用一个普通 POJO 承接查询参数,配合 @Valid 做校验。注意 Spring Boot 3 的校验注解在 jakarta.validation.constraints 包下,使用前需要引入 spring-boot-starter-validation 依赖。

public class PageParam {

    @Min(value = 1, message = "页码最小为 1")
    private int pageNum = 1;

    @Min(value = 1, message = "每页条数最小为 1")
    @Max(value = 100, message = "每页条数最大为 100")
    private int pageSize = 20;

    private String sortBy;
    private String sortDir = "desc";

    // 省略 getter / setter

    /** 偏移量,供 SQL 的 LIMIT 或内存分页使用。 */
    public int offset() {
        return (pageNum - 1) * pageSize;
    }

    /** 兜底归一化:即使绕过校验,也保证参数落在合法区间。 */
    public PageParam normalize() {
        if (pageNum < 1) {
            pageNum = 1;
        }
        if (pageSize < 1) {
            pageSize = 20;
        }
        if (pageSize > 100) {
            pageSize = 100;
        }
        return this;
    }
}

PageResult:固定返回结构

用一个泛型记录类统一返回体,pages 由 total 和 pageSize 计算得出,total 为 0 时 pages 为 0:

public record PageResult<T>(List<T> list, long total,
                             int pageNum, int pageSize, int pages) {

    public static <T> PageResult<T> of(List<T> list, long total, PageParam param) {
        int pages = total == 0 ? 0
                : (int) Math.ceil((double) total / param.getPageSize());
        return new PageResult<>(list, total,
                param.getPageNum(), param.getPageSize(), pages);
    }
}

接口层与服务层:各做各的事

Controller 只负责接收与校验,不写分页逻辑;Service 只负责查库与组装结果。GET 请求的参数绑定用 @ModelAttribute,@Valid 触发校验:

@GetMapping("/users")
public PageResult<UserVO> list(@Valid @ModelAttribute PageParam param) {
    return userService.list(param.normalize());
}

Service 层用 Spring Data 的 PageRequest 做分页查询。注意 PageRequest 的页码从 0 开始,所以要把 pageNum 减 1 再传入;排序字段先过白名单再拼 Sort:

private static final Set<String> ALLOWED_SORT_FIELDS =
        Set.of("id", "createTime", "name");

public PageResult<UserVO> list(PageParam param) {
    String sortBy = ALLOWED_SORT_FIELDS.contains(param.getSortBy())
            ? param.getSortBy() : "id";
    Sort sort = "asc".equalsIgnoreCase(param.getSortDir())
            ? Sort.by(sortBy).ascending()
            : Sort.by(sortBy).descending();
    Pageable pageable = PageRequest.of(
            param.getPageNum() - 1, param.getPageSize(), sort);
    Page<User> page = userRepository.findAll(pageable);
    List<UserVO> vos = page.getContent().stream()
            .map(UserVO::from).toList();
    return PageResult.of(vos, page.getTotalElements(), param);
}

其中 UserVO::from 是项目里自己写的静态转换方法,按实际字段把实体转成视图对象,不属于框架 API。

注意点

  • 不要把 offset 交给前端传:前端只传 pageNum 和 pageSize,offset 由后端算,避免越权翻到不该看的数据区间。
  • 校验与归一化都要有:@Valid 负责返回友好的参数错误,normalize 负责在校验被绕过或默认值异常时仍不查崩。
  • pageSize 上限写死在代码里:不要做成可配置的超大值,列表接口的上限首先是保护数据库,其次才是体验。
  • total 必须用 count 查询:不要用查出的 list 长度冒充总数,否则前端算出的总页数永远是 1。
  • 排序方向只认 asc 与 desc:其它值一律按 desc 处理,不要把原始字符串拼进 SQL 或 Sort。
  • 小数据量字典表可以直接内存分页:数据量很小的表可以用 subList 切片,但要先判越界,from 超过 size 时返回空列表而不是抛异常;数据量大的表必须用 PageRequest 走数据库分页。

常见错误

  • pageNum 从 0 开始传给 PageRequest 时忘了减 1,第一页直接跳过。
  • 只在 Controller 校验 pageSize,却在别的入口复用 Service 时漏了归一化。
  • 返回结构里缺 pages 字段,前端每个列表页都要自己算总页数。
  • sortBy 直接拼进查询条件,传入不存在的字段就报 500。

这套写法的核心就一句话:分页参数只在一个类里收敛,返回结构只在一个类里定型。后续再加列表接口时,Controller 与 Service 按上面的样子各写几行即可,不用再为分页逻辑单独写分支。