SpringBoot中Pageable分頁參數(shù)的自動提取與全局復用

更新時間：2026年02月05日 08:42:15 作者：大尚來也

在現(xiàn)代 Web 應用開發(fā)中,分頁是處理大量數(shù)據(jù)的標配功能,本文將帶你實現(xiàn) 分頁參數(shù)的自動提取、自定義配置與全局復用,感興趣的小伙伴可以跟隨小編一起學習一下

在現(xiàn)代 Web 應用開發(fā)中，分頁是處理大量數(shù)據(jù)的標配功能。Spring Boot 通過 Spring Data 提供了強大的分頁支持——只需在 Controller 方法中聲明 Pageable 參數(shù)，框架便能自動從請求中解析 page、size、sort 等參數(shù)并構建分頁對象。然而，在真實項目中，我們常面臨兩個痛點：

默認分頁參數(shù)不符合業(yè)務需求（如 page 從 0 開始 vs 用戶習慣從 1 開始）
分頁邏輯重復散落在多個接口中，難以統(tǒng)一維護

本文將帶你實現(xiàn) 分頁參數(shù)的自動提取、自定義配置與全局復用，讓分頁邏輯既靈活又 DRY（Don’t Repeat Yourself）。

一、Spring Boot 默認分頁機制回顧

Spring Data 提供了 Pageable 接口（通常由 PageRequest 實現(xiàn)），配合 @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 表示第一頁
需要限制最大分頁大小（防刷）
統(tǒng)一分頁響應格式（如包含 totalElements、totalPages 等）
多個模塊重復寫分頁邏輯，難以統(tǒng)一調整

三、解決方案：自定義 Pageable 解析器

步驟 1：配置 Spring 的 Pageable 處理策略

在配置類中，通過 PageableHandlerMethodArgumentResolverCustomizer 自定義默認行為：

@Configuration
public class WebConfig {

    @Bean
    public PageableHandlerMethodArgumentResolverCustomizer pageableCustomizer() {
        return resolver -> {
            resolver.setOneIndexedParameters(true); // 啟用 page=1 表示第一頁
            resolver.setMaxPageSize(100);           // 限制最大每頁條數(shù)
            resolver.setFallbackPageable(PageRequest.of(0, 20)); // 默認分頁
        };
    }
}

效果：所有 Controller 中的 Pageable 參數(shù)自動按新規(guī)則解析！

步驟 2：統(tǒng)一封裝分頁響應（可選但推薦）

創(chuàng)建通用分頁結果類，避免每次手動組裝：

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（適用于復雜場景）

若需額外分頁參數(shù)（如搜索關鍵詞、狀態(tài)過濾等），可封裝專用 DTO：

public class UserQuery {
    private String keyword;
    private String status;
    // 分頁參數(shù)通過繼承或組合 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 實現(xiàn)自動轉換。

五、全局異常處理：攔截非法分頁參數(shù)

結合 @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("無效的頁碼"));
        }
        // 其他異常處理...
    }
}