Spring Boot MongoDB 分頁工具類封裝 (新手指南)
目錄
- 引言:為何需要分頁工具類?
- 工具類一:
PaginationUtils
- 簡化Pageable
創建- 設計目標
- 代碼實現 (
PaginationUtils.java
) - 如何使用
PaginationUtils
- 工具類二:
PageResponse<T>
- 標準化分頁響應 DTO- 設計目標
- 代碼實現 (
PageResponse.java
) - 如何使用
PageResponse<T>
- 整合示例:在 Controller 和 Service 中使用工具類
- Controller 層 (
UserController.java
) - Service 層 (
UserService.java
)
- Controller 層 (
- 重點內容總結
- 結語
1. 引言:為何需要分頁工具類?
在之前的筆記中,我們學習了如何使用 Pageable
和 Page
來實現分頁。雖然 Spring Data 提供了基礎,但在實際項目中,我們經常會重復以下操作:
- 從 HTTP 請求參數(頁碼、大小、排序字段、排序方向)創建
Pageable
對象。 - 處理 用戶友好的 1-based 頁碼 與 Spring Data 內部 0-based 頁碼 之間的轉換。
- 處理排序參數的解析和
Sort
對象的構建。 - 可能希望 標準化 API 返回的分頁信息格式,使其更簡潔或符合前端特定需求,而不是直接暴露 Spring Data 的
Page
結構。
封裝分頁工具類可以:
- 減少重復代碼:將通用的分頁邏輯集中處理。
- 提高可讀性:使 Service 和 Controller 層的代碼更專注于業務邏輯。
- 統一規范:確保項目中分頁參數處理和響應格式的一致性。
- 簡化使用:讓新手更容易地實現正確的分頁。
2. 工具類一:PaginationUtils
- 簡化 Pageable
創建
這個工具類的主要職責是接收前端傳入的原始分頁參數,并安全、便捷地將其轉換為 Spring Data 所需的 Pageable
對象。
設計目標
- 接收 1-based 頁碼,內部轉換為 0-based。
- 提供默認的頁碼和頁面大小。
- 支持單個或多個排序字段及方向的解析。
- 處理無效或缺失的參數,提供合理的默認行為(如不排序)。
代碼實現 (PaginationUtils.java
)
package com.example.yourproject.utils; // 根據你的項目結構調整包名import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.util.CollectionUtils; // Spring 提供的集合工具類
import org.springframework.util.StringUtils; // Spring 提供的字符串工具類import java.util.ArrayList;
import java.util.List;/*** 分頁工具類** 幫助從原始請求參數創建 Spring Data Pageable 對象。* 核心功能:處理 1-based 頁碼轉換、默認值、排序參數解析。*/
public final class PaginationUtils { // final class, 防止被繼承// 默認頁碼(用戶傳入的第一頁)private static final int DEFAULT_PAGE_NUMBER = 1;// 默認每頁大小private static final int DEFAULT_PAGE_SIZE = 10;// 默認排序方向private static final Sort.Direction DEFAULT_SORT_DIRECTION = Sort.Direction.ASC;// 排序參數中,字段和方向的分隔符(例如 "name,desc")private static final String SORT_DELIMITER = ",";/*** 私有構造函數,防止實例化工具類*/private PaginationUtils() {throw new UnsupportedOperationException("This is a utility class and cannot be instantiated");}/*** 創建 Pageable 對象。** @param pageInput 用戶傳入的頁碼 (從 1 開始計數)。如果為 null 或小于 1,則使用默認值 1。* @param sizeInput 用戶傳入的每頁大小。如果為 null 或小于 1,則使用默認值 10。* @param sortInput 排序參數列表。每個字符串格式為 "fieldName,direction" (例如 "name,asc", "age,desc")。* direction 可以省略,默認為升序 (ASC)。* 如果列表為空或 null,則不進行排序。* @return 配置好的 Pageable 對象。*/public static Pageable createPageable(Integer pageInput, Integer sizeInput, List<String> sortInput) {// 1. 驗證并設置頁碼 (轉換為 0-based)// 如果 pageInput 為 null 或 < 1,則使用默認頁碼 1。然后減 1 得到 0-based 頁碼。int page = (pageInput == null || pageInput < 1) ? DEFAULT_PAGE_NUMBER - 1 : pageInput - 1;// 2. 驗證并設置頁面大小// 如果 sizeInput 為 null 或 < 1,則使用默認大小 10。int size = (sizeInput == null || sizeInput < 1) ? DEFAULT_PAGE_SIZE : sizeInput;// 3. 解析排序參數Sort sort = parseSort(sortInput);// 4. 創建并返回 PageRequest 對象return PageRequest.of(page, size, sort);}/*** 創建帶有默認排序的 Pageable 對象(如果未提供排序參數)。** @param pageInput 用戶傳入的頁碼 (從 1 開始計數)。* @param sizeInput 用戶傳入的每頁大小。* @param sortInput 排序參數列表 (同上)。* @param defaultSort 默認的 Sort 對象。如果 sortInput 為空或無效,則使用此默認排序。* @return 配置好的 Pageable 對象。*/public static Pageable createPageable(Integer pageInput, Integer sizeInput, List<String> sortInput, Sort defaultSort) {int page = (pageInput == null || pageInput < 1) ? DEFAULT_PAGE_NUMBER - 1 : pageInput - 1;int size = (sizeInput == null || sizeInput < 1) ? DEFAULT_PAGE_SIZE : sizeInput;Sort sort = parseSort(sortInput);// 如果解析出的 sort 是 unsorted,并且提供了默認 sort,則使用默認 sortif (sort.isUnsorted() && defaultSort != null && defaultSort.isSorted()) {sort = defaultSort;}return PageRequest.of(page, size, sort);}/*** 解析排序參數字符串列表,構建 Sort 對象。** @param sortParams 排序參數列表,每個元素如 "field,direction" 或 "field"。* @return 如果參數有效則返回 Sort 對象,否則返回 Sort.unsorted()。*/private static Sort parseSort(List<String> sortParams) {if (CollectionUtils.isEmpty(sortParams)) {return Sort.unsorted(); // 沒有提供排序參數,返回不排序}List<Sort.Order> orders = new ArrayList<>();for (String sortParam : sortParams) {// 跳過空或空白的排序參數if (!StringUtils.hasText(sortParam)) {continue;}String[] parts = sortParam.split(SORT_DELIMITER);// 第一個部分是字段名,必須存在String property = parts[0].trim();if (!StringUtils.hasText(property)) {continue; // 字段名為空,跳過}// 獲取排序方向,如果沒提供或無效,則使用默認方向Sort.Direction direction = DEFAULT_SORT_DIRECTION;if (parts.length > 1 && StringUtils.hasText(parts[1])) {// 嘗試從字符串解析方向 (忽略大小寫)try {direction = Sort.Direction.fromString(parts[1].trim());} catch (IllegalArgumentException e) {// 如果方向字符串無效 (例如 "ascend", "descend"), 使用默認值System.err.println("Invalid sort direction: " + parts[1] + ". Using default: " + DEFAULT_SORT_DIRECTION);// 這里可以選擇打印日志或忽略錯誤}}// 創建 Sort.Order 對象并添加到列表orders.add(new Sort.Order(direction, property));}// 如果成功解析出至少一個有效的 Order,則創建 Sort 對象,否則返回 unsortedreturn orders.isEmpty() ? Sort.unsorted() : Sort.by(orders);}}
注釋說明:
final class
/private constructor
: 這是工具類的標準寫法,表明它不應該被繼承或實例化。所有方法都是靜態的。- 常量定義: 定義默認值和分隔符,方便修改和維護。
createPageable
方法:- 接收
Integer
類型的pageInput
和sizeInput
,允許傳入null
。 - 核心:
page = (pageInput == null || pageInput < 1) ? DEFAULT_PAGE_NUMBER - 1 : pageInput - 1;
這行處理了null
值、小于 1 的無效值,并將用戶習慣的 1-based 頁碼轉換成 Spring Data 需要的 0-based 頁碼。 - 調用
parseSort
方法處理排序參數。 - 最后使用
PageRequest.of(page, size, sort)
創建Pageable
實例。
- 接收
createPageable
(重載): 提供了一個可以傳入默認Sort
對象的版本,當用戶沒有提供任何有效排序時,可以使用這個默認排序。parseSort
方法:- 處理
null
或空列表的情況,返回Sort.unsorted()
。 - 遍歷
sortInput
列表中的每個字符串。 - 使用
split(SORT_DELIMITER)
分割字段名和方向。 - 進行健壯性檢查 (字段名是否為空)。
- 解析排序方向,使用
Sort.Direction.fromString()
并包含try-catch
處理無效方向字符串,回退到默認方向。 - 創建
Sort.Order
對象。 - 最后使用
Sort.by(orders)
將所有有效的Order
組合成Sort
對象。如果列表為空,則Sort.by()
返回Sort.unsorted()
。
- 處理
- 依賴: 使用了 Spring Framework 提供的
StringUtils
和CollectionUtils
進行空值檢查,這是推薦的做法。
如何使用 PaginationUtils
在你的 Service 層 或 Controller 層(取決于你處理分頁參數的位置,通常在 Service 層更合適),你可以這樣調用:
// 假設在 Service 層
import com.example.yourproject.utils.PaginationUtils;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import java.util.List;// ...public Page<User> findUsersPaginated(Integer page, Integer size, List<String> sort) {// 使用工具類創建 Pageable 對象// 假設我們希望默認按 "createdAt" 降序排序Sort defaultSort = Sort.by(Sort.Direction.DESC, "createdAt");Pageable pageable = PaginationUtils.createPageable(page, size, sort, defaultSort);// 現在可以直接將 pageable 傳遞給 Repository 方法return userRepository.findAll(pageable); // 或者 userRepository.findByXXX(..., pageable);
}
3. 工具類二:PageResponse<T>
- 標準化分頁響應 DTO
這個類是一個數據傳輸對象 (DTO),用于包裝分頁查詢的結果,提供一個統一、簡潔的 JSON 結構給前端。
設計目標
- 封裝當前頁的數據列表 (
List<T>
)。 - 提供清晰的分頁元數據(當前頁碼 (1-based)、每頁大小、總記錄數、總頁數、是否首頁/末頁)。
- 隱藏 Spring Data
Page
對象的內部復雜結構。 - 提供一個靜態工廠方法,方便從
Page<T>
對象轉換。
代碼實現 (PageResponse.java
)
package com.example.yourproject.dto; // DTO 通常放在 dto 包下import org.springframework.data.domain.Page;
import java.util.List;/*** 標準化的分頁響應體 DTO (Data Transfer Object)** 用于封裝分頁查詢結果,提供給 API 調用者一個簡潔一致的結構。** @param <T> 數據的實體類型*/
public class PageResponse<T> {private final List<T> content; // 當前頁的數據列表private final int currentPage; // 當前頁碼 (從 1 開始)private final int pageSize; // 每頁大小private final long totalElements; // 總記錄數private final int totalPages; // 總頁數private final boolean first; // 是否為第一頁private final boolean last; // 是否為最后一頁/*** 構造函數 (私有或包私有,推薦使用靜態工廠方法創建)*/private PageResponse(List<T> content, int currentPage, int pageSize, long totalElements, int totalPages, boolean first, boolean last) {this.content = content;this.currentPage = currentPage;this.pageSize = pageSize;this.totalElements = totalElements;this.totalPages = totalPages;this.first = first;this.last = last;}/*** 靜態工廠方法:從 Spring Data Page 對象創建 PageResponse 對象。* @param page Spring Data 的 Page 對象* @param <T> 數據的實體類型* @return 轉換后的 PageResponse 對象*/public static <T> PageResponse<T> fromPage(Page<T> page) {if (page == null) {// 可以選擇返回 null,或者一個表示空的 PageResponse,取決于你的 API 設計return new PageResponse<>(List.of(), 1, 0, 0L, 0, true, true); // 返回一個空響應示例// throw new IllegalArgumentException("Page object cannot be null");}return new PageResponse<>(page.getContent(), // 獲取數據列表page.getNumber() + 1, // **核心轉換:0-based to 1-based**page.getSize(), // 獲取頁面大小page.getTotalElements(), // 獲取總記錄數page.getTotalPages(), // 獲取總頁數page.isFirst(), // 是否第一頁page.isLast() // 是否最后頁);}// --- Getters ---public List<T> getContent() {return content;}public int getCurrentPage() {return currentPage;}public int getPageSize() {return pageSize;}public long getTotalElements() {return totalElements;}public int getTotalPages() {return totalPages;}public boolean isFirst() {return first;}public boolean isLast() {return last;}/** 預期 JSON 輸出示例:* {* "content": [ ... data objects ... ],* "currentPage": 1,* "pageSize": 10,* "totalElements": 153,* "totalPages": 16,* "first": true,* "last": false* }*/
}
注釋說明:
- 泛型
<T>
: 使PageResponse
可以用于任何類型的分頁數據。 - 字段: 只包含前端最關心的分頁信息,字段名清晰。
currentPage
特別設計為 1-based。 - 構造函數: 設為
private
,強制使用靜態工廠方法創建實例,這是一種良好的實踐。 fromPage
靜態工廠方法:- 接收一個 Spring Data
Page<T>
對象作為輸入。 - 做了
null
檢查。 - 核心:
page.getNumber() + 1
將 Spring Data 的 0-based 頁碼轉換為用戶友好的 1-basedcurrentPage
。 - 從
Page<T>
對象中提取所有需要的數據,填充到PageResponse
的字段中。
- 接收一個 Spring Data
- Getters: 提供公共的 getter 方法,以便 Jackson 等庫能正確地將對象序列化為 JSON。
- JSON 示例: 注釋中給出了預期的 JSON 輸出格式,方便前后端對接。
如何使用 PageResponse<T>
在你的 Service 層 方法中,當從 Repository 獲取到 Page<T>
對象后,使用 PageResponse.fromPage()
進行轉換。然后 Controller 層 直接返回這個 PageResponse<T>
對象。
// 假設在 Service 層
import com.example.yourproject.dto.PageResponse;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;// ...public PageResponse<User> findUsersPaginatedAndWrapped(Integer page, Integer size, List<String> sort) {Sort defaultSort = Sort.by(Sort.Direction.DESC, "createdAt");Pageable pageable = PaginationUtils.createPageable(page, size, sort, defaultSort);// 1. 從 Repository 獲取 Page<User> 對象Page<User> userPage = userRepository.findAll(pageable);// 2. 使用 PageResponse.fromPage() 轉換PageResponse<User> pageResponse = PageResponse.fromPage(userPage);// 3. 返回轉換后的 PageResponse 對象return pageResponse;
}
4. 整合示例:在 Controller 和 Service 中使用工具類
下面展示如何在 Controller 和 Service 中協同使用這兩個工具類。
Controller 層 (UserController.java
)
Controller 負責接收 HTTP 請求參數,并將其傳遞給 Service 層。注意 @RequestParam
中 sort
參數的處理。
package com.example.yourproject.controller;import com.example.yourproject.dto.PageResponse; // 導入 DTO
import com.example.yourproject.model.User;
import com.example.yourproject.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;import java.util.List; // 需要導入 List@RestController
@RequestMapping("/api/users")
public class UserController {@Autowiredprivate UserService userService; // 假設 UserService 已更新/*** 獲取用戶列表 (使用分頁工具類)** @param page API 接收的頁碼 (通常從 1 開始)。* @param size 每頁大小。* @param sort 排序參數列表。可以接收多個 sort 參數,* 例如: /api/users?sort=name,asc&sort=age,desc* Spring 會自動將其收集到 List<String> 中。* @return ResponseEntity 包裝的 PageResponse<User> 對象。*/@GetMappingpublic ResponseEntity<PageResponse<User>> getAllUsersPaginated(@RequestParam(required = false) Integer page, // required=false 讓參數可選@RequestParam(required = false) Integer size,@RequestParam(required = false) List<String> sort) { // 接收排序參數列表// 調用更新后的 Service 方法,傳入原始參數PageResponse<User> userPageResponse = userService.findUsersPaginatedAndWrapped(page, size, sort);// 返回標準化的 PageResponse DTOreturn ResponseEntity.ok(userPageResponse);}
}
關鍵點:
@RequestParam(required = false)
: 允許page
,size
,sort
參數在請求中不提供,PaginationUtils
會使用默認值。@RequestParam List<String> sort
: Spring MVC 非常智能,如果 URL 中出現多個同名參數 (?sort=name,asc&sort=age,desc
),它能自動將這些值收集到一個List<String>
中。這正好符合我們PaginationUtils
的設計!
Service 層 (UserService.java
)
Service 層使用 PaginationUtils
創建 Pageable
,調用 Repository,然后使用 PageResponse.fromPage()
包裝結果。
package com.example.yourproject.service;import com.example.yourproject.dto.PageResponse; // 導入 DTO
import com.example.yourproject.model.User;
import com.example.yourproject.repository.UserRepository;
import com.example.yourproject.utils.PaginationUtils; // 導入工具類
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.stereotype.Service;import java.util.List;@Service
public class UserService {@Autowiredprivate UserRepository userRepository;/*** 分頁查詢用戶,并使用 PageResponse DTO 包裝結果。** @param pageInput 來自 Controller 的頁碼 (1-based)* @param sizeInput 來自 Controller 的每頁大小* @param sortInput 來自 Controller 的排序參數列表* @return PageResponse<User> 適合返回給客戶端*/public PageResponse<User> findUsersPaginatedAndWrapped(Integer pageInput, Integer sizeInput, List<String> sortInput) {// 定義默認排序(可選,如果希望在用戶未指定排序時應用)Sort defaultSort = Sort.by(Sort.Direction.DESC, "createdAt"); // 例如,默認按創建時間降序// 1. 使用 PaginationUtils 創建 Pageable// 將 Controller 傳來的原始參數交給工具類處理Pageable pageable = PaginationUtils.createPageable(pageInput, sizeInput, sortInput, defaultSort);// 2. 調用 Repository 進行查詢Page<User> userPage = userRepository.findAll(pageable);// Page<User> userPage = userRepository.findBySomeCondition(..., pageable); // 也可以用于條件查詢// 3. 使用 PageResponse DTO 轉換結果// 這一步將 Page<User> 轉換成前端友好的 PageResponse<User>return PageResponse.fromPage(userPage);}
}
5. 重點內容總結
PaginationUtils
:- 核心職責: 將請求參數(1-based 頁碼、大小、排序字符串列表)轉換為
Pageable
對象。 - 關鍵特性: 自動處理 1-based 到 0-based 頁碼轉換、參數默認值、復雜排序參數 (
"field,direction"
) 解析。 - 使用位置: 通常在 Service 層調用,用于準備傳遞給 Repository 的
Pageable
。
- 核心職責: 將請求參數(1-based 頁碼、大小、排序字符串列表)轉換為
PageResponse<T>
:- 核心職責: 作為分頁查詢結果的標準化 DTO,提供簡潔一致的 API 響應結構。
- 關鍵特性: 包含數據列表 (
content
) 和清晰的分頁元數據(1-basedcurrentPage
,totalElements
,totalPages
等),通過靜態工廠方法fromPage(Page<T>)
方便地從 Spring DataPage
對象轉換。 - 使用位置: 在 Service 層將
Page<T>
結果轉換為PageResponse<T>
,然后 Controller 直接返回此對象。
- 好處:
- 簡化: 大幅減少 Controller 和 Service 中的樣板代碼。
- 健壯: 統一處理參數驗證和默認值。
- 清晰: 使代碼更易讀,API 響應更規范。
- 易用: 對新手友好,隱藏了分頁實現的細節。
- Controller 參數綁定: 利用
@RequestParam List<String> sort
可以優雅地接收多個排序參數。
6. 結語
通過封裝 PaginationUtils
和 PageResponse<T>
這兩個工具類,你可以極大地簡化 Spring Boot 項目中 MongoDB(或其他 Spring Data 支持的數據庫)的分頁實現。這不僅提高了開發效率,也使得代碼更加規范和易于維護,尤其是在團隊協作或項目規模變大時。希望這份詳細的筆記能幫助你輕松掌握并運用這些分頁工具!