优雅分页：Spring Boot 中 Pageable 参数的自动提取与全局复用实践

在现代 Web 应用开发中，分页是处理大量数据的标配功能。Spring Boot 通过 Spring Data 提供了强大的分页支持------只需在 Controller 方法中声明 Pageable 参数，框架便能自动从请求中解析 page、size、sort 等参数并构建分页对象。然而，在真实项目中，我们常面临两个痛点：

1. 默认分页参数不符合业务需求（如 page 从 0 开始 vs 用户习惯从 1 开始）
2. 分页逻辑重复散落在多个接口中，难以统一维护

本文将带你实现 分页参数的自动提取、自定义配置与全局复用，让分页逻辑既灵活又 DRY（Don't Repeat Yourself）。

---

一、Spring Boot 默认分页机制回顾

Spring Data 提供了 Pageable 接口（通常由 PageRequest 实现），配合 @EnableSpringDataWebSupport（Spring Boot 2.x+ 默认启用），可直接在 Controller 中使用：

@GetMapping("/users")
public Page<User> getUsers(Pageable pageable) {
    return userService.findAll(pageable);
}

前端请求示例：

GET /users?page=0&size=10&sort=name,asc

⚠️ 注意：page 默认从 0 开始，这常与前端"第1页"的认知冲突。

---

二、痛点：为什么需要自定义？

• 前端希望 page=1 表示第一页
• 需要限制最大分页大小（防刷）
• 统一分页响应格式（如包含 totalElements、totalPages 等）
• 多个模块重复写分页逻辑，难以统一调整

---

三、解决方案：自定义 Pageable 解析器

步骤 1：配置 Spring 的 Pageable 处理策略

在配置类中，通过 PageableHandlerMethodArgumentResolverCustomizer 自定义默认行为：

@Configuration
public class WebConfig {

    @Bean
    public PageableHandlerMethodArgumentResolverCustomizer pageableCustomizer() {
        return resolver -> {
            resolver.setOneIndexedParameters(true); // 启用 page=1 表示第一页
            resolver.setMaxPageSize(100);           // 限制最大每页条数
            resolver.setFallbackPageable(PageRequest.of(0, 20)); // 默认分页
        };
    }
}

✅ 效果：所有 Controller 中的 Pageable 参数自动按新规则解析！

---

步骤 2：统一封装分页响应（可选但推荐）

创建通用分页结果类，避免每次手动组装：

public class PageResult<T> {
    private List<T> content;
    private long totalElements;
    private int totalPages;
    private int pageNumber; // 1-based
    private int pageSize;

    // 构造方法 + getter/setter
    public static <T> PageResult<T> of(Page<T> page) {
        PageResult<T> result = new PageResult<>();
        result.content = page.getContent();
        result.totalElements = page.getTotalElements();
        result.totalPages = page.getTotalPages();
        result.pageNumber = page.getNumber() + 1; // 转为 1-based
        result.pageSize = page.getSize();
        return result;
    }
}

Controller 使用示例：

@GetMapping("/users")
public PageResult<User> getUsers(Pageable pageable) {
    Page<User> page = userService.findAll(pageable);
    return PageResult.of(page);
}

---

四、进阶：自定义分页 DTO（适用于复杂场景）

若需额外分页参数（如搜索关键词、状态过滤等），可封装专用 DTO：

public class UserQuery {
    private String keyword;
    private String status;
    // 分页参数通过继承或组合 Pageable 获取
    private Pageable pageable;

    // 或者手动解析
    private Integer page = 1;
    private Integer size = 20;

    public Pageable toPageable() {
        return PageRequest.of(
            Math.max(0, page - 1), 
            Math.min(size, 100),
            Sort.by("createTime").descending()
        );
    }
}

然后在 Controller 中使用 @ModelAttribute 或手动绑定：

@GetMapping("/users")
public PageResult<User> getUsers(UserQuery query) {
    Page<User> page = userService.search(query.getKeyword(), query.getStatus(), query.toPageable());
    return PageResult.of(page);
}

🔧 提示：可通过 @InitBinder 或自定义 Converter 实现自动转换。

---

五、全局异常处理：拦截非法分页参数

结合 @ControllerAdvice，对超出范围的分页请求友好提示：

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception e) {
        if (e instanceof IllegalArgumentException && e.getMessage().contains("Page index")) {
            return ResponseEntity.badRequest().body(new ErrorResponse("无效的页码"));
        }
        // 其他异常处理...
    }
}

---

六、总结

通过合理利用 Spring Boot 的扩展点，我们可以：

• ✅ 将分页参数解析规则 集中配置
• ✅ 统一前后端分页语义（1-based）
• ✅ 限制资源滥用（maxPageSize）
• ✅ 封装通用响应结构，提升代码一致性

真正的工程优雅，不在于炫技，而在于把重复的问题一次性解决干净。 下次当你再写分页接口时，不妨试试这套方案------让你的代码更简洁，团队协作更顺畅。