问题:每个列表接口都重写一遍分页
做后台管理系统时,几乎每个列表接口都要分页:用户列表、订单列表、日志列表。如果每个接口各自接收 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 按上面的样子各写几行即可,不用再为分页逻辑单独写分支。