Spring Boot MongoDB 分页工具类封装 (新手指南)

！！！5252025-04-11 12:48

Spring Boot MongoDB 分页工具类封装 (新手指南)

目录

  1. 引言：为何需要分页工具类？
  2. [工具类一：PaginationUtils - 简化 Pageable 创建](#工具类一：PaginationUtils - 简化 Pageable 创建)
  3. [工具类二：PageResponse<T> - 标准化分页响应 DTO](#工具类二：PageResponse<T> - 标准化分页响应 DTO)
  4. [整合示例：在 Controller 和 Service 中使用工具类](#整合示例：在 Controller 和 Service 中使用工具类)
    • [Controller 层 (UserController.java)](#Controller 层 (UserController.java))
    • [Service 层 (UserService.java)](#Service 层 (UserService.java))
  5. 重点内容总结
  6. 结语

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)

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，则使用默认 sort
        if (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 对象，否则返回 unsorted
        return 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 层更合适），你可以这样调用：

java 复制代码 
// 假设在 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)

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-based currentPage。
    • 从 Page<T> 对象中提取所有需要的数据，填充到 PageResponse 的字段中。
  • Getters: 提供公共的 getter 方法，以便 Jackson 等库能正确地将对象序列化为 JSON。
  • JSON 示例: 注释中给出了预期的 JSON 输出格式，方便前后端对接。

如何使用 PageResponse<T>

在你的 Service 层 方法中，当从 Repository 获取到 Page<T> 对象后，使用 PageResponse.fromPage() 进行转换。然后 Controller 层 直接返回这个 PageResponse<T> 对象。

java 复制代码 
// 假设在 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 参数的处理。

java 复制代码 
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 {

    @Autowired
    private 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> 对象。
     */
    @GetMapping
    public 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 DTO
        return 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() 包装结果。

java 复制代码 
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 {

    @Autowired
    private 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. 重点内容总结

  1. PaginationUtils :
    • 核心职责 : 将请求参数（1-based 页码、大小、排序字符串列表）转换为 Pageable 对象。
    • 关键特性 : 自动处理 1-based 到 0-based 页码转换、参数默认值、复杂排序参数 ("field,direction") 解析。
    • 使用位置 : 通常在 Service 层调用，用于准备传递给 Repository 的 Pageable。
  2. PageResponse<T> :
    • 核心职责 : 作为分页查询结果的标准化 DTO，提供简洁一致的 API 响应结构。
    • 关键特性 : 包含数据列表 (content) 和清晰的分页元数据（1-based currentPage, totalElements, totalPages 等），通过静态工厂方法 fromPage(Page<T>) 方便地从 Spring Data Page 对象转换。
    • 使用位置 : 在 Service 层将 Page<T> 结果转换为 PageResponse<T>，然后 Controller 直接返回此对象。
  3. 好处 :
    • 简化: 大幅减少 Controller 和 Service 中的样板代码。
    • 健壮: 统一处理参数验证和默认值。
    • 清晰: 使代码更易读，API 响应更规范。
    • 易用: 对新手友好，隐藏了分页实现的细节。
  4. Controller 参数绑定 : 利用 @RequestParam List<String> sort 可以优雅地接收多个排序参数。

6. 结语

通过封装 PaginationUtils 和 PageResponse<T> 这两个工具类，你可以极大地简化 Spring Boot 项目中 MongoDB（或其他 Spring Data 支持的数据库）的分页实现。这不仅提高了开发效率，也使得代码更加规范和易于维护，尤其是在团队协作或项目规模变大时。希望这份详细的笔记能帮助你轻松掌握并运用这些分页工具！

相关推荐
橘猫云计算机设计2 小时前
基于php的成绩分析和预警与预测网站(源码+lw+部署文档+讲解)，源码可白嫖!
开发语言·后端·信息可视化·毕业设计·php
Java小陆2 小时前
Java基础-Collection单列集合
后端
Java小陆2 小时前
Java基础--正则表达式
后端
枫super2 小时前
Servlet、HTTP与Spring Boot Web全面解析与整合指南
spring boot·后端·http·servlet·java-ee·idea·javase
张哈大2 小时前
lombok注解不起作用
后端
Asthenia04122 小时前
数据通信技术复习笔记：差错控制-奇偶监督/汉明码/循环码
后端
探索为何2 小时前
SQL解析器系列：实现ALTER TABLE语句
后端·架构
Aurora_Trip2 小时前
内存池使用手册
后端·面试
海风极客2 小时前
快来看！你的Go代码还能更优雅
后端·代码规范
碣石潇湘无限路2 小时前
【技术】Ruby 生态概念速查表，通过对比nodejs生态（入门）
开发语言·经验分享·笔记·后端·node.js·ruby
热门推荐
01我决定放弃搞 Java 了02RAG 实践- Ollama+RagFlow 部署本地知识库03从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑04Vue3 + TypeScript 的 Hooks 实用示例05DeepSeek RAGFlow构建本地知识库系统06如何在WPS和Word/Excel中直接使用DeepSeek功能07游戏引擎学习第217天08汽车上的各种质量：整备质量、总质量、装载质量、簧上质量、簧下质量09DeepSeek各版本说明与优缺点分析10【WRF理论第十三期】详细介绍 Registry 的作用、结构和内容