java 分页工具类（PaginationUtils）

Java 分页工具类（PaginationUtils）

引言

在开发 web 应用和 API 服务时，分页是一种常见且有效的技术，用于处理和显示大量数据。分页不仅能提高响应速度，还能减少服务器和客户端的负载。为了简化分页操作，可以封装一个工具类来实现分页逻辑。

PaginationUtils 简介

PaginationUtils 是一个自定义的 Java 工具类，用于处理数据分页。它提供了分页计算、数据分割、分页参数验证等功能，通过对分页操作的封装，使得分页处理更为简洁和高效。PaginationUtils 可以应用于列表、数据库查询结果等多种数据源的分页场景。

PaginationUtils 工具类实现

以下是 PaginationUtils 工具类的完整实现，包含了分页计算、分页结果封装、参数验证等方法。

import java.util.List;
import java.util.ArrayList;

public class PaginationUtils {

    // 分页结果封装类
    public static class Page<T> {
        private int currentPage;   // 当前页码
        private int pageSize;      // 每页大小
        private int totalItems;    // 总记录数
        private int totalPages;    // 总页数
        private List<T> items;     // 当前页的数据

        public Page(int currentPage, int pageSize, int totalItems, List<T> items) {
            this.currentPage = currentPage;
            this.pageSize = pageSize;
            this.totalItems = totalItems;
            this.items = items;
            this.totalPages = (int) Math.ceil((double) totalItems / pageSize);
        }

        // Getters
        public int getCurrentPage() {
            return currentPage;
        }

        public int getPageSize() {
            return pageSize;
        }

        public int getTotalItems() {
            return totalItems;
        }

        public int getTotalPages() {
            return totalPages;
        }

        public List<T> getItems() {
            return items;
        }

        @Override
        public String toString() {
            return String.format("Page %d of %d, Showing %d of %d items",
                    currentPage, totalPages, items.size(), totalItems);
        }
    }

    // 验证并修正分页参数
    public static int validatePageNumber(int pageNumber) {
        return pageNumber < 1 ? 1 : pageNumber;
    }

    public static int validatePageSize(int pageSize) {
        int defaultSize = 10;
        int maxSize = 100;
        if (pageSize < 1) {
            return defaultSize;
        }
        return Math.min(pageSize, maxSize);
    }

    // 计算起始索引
    public static int calculateStartIndex(int currentPage, int pageSize) {
        return (currentPage - 1) * pageSize;
    }

    // 获取分页数据
    public static <T> Page<T> paginate(List<T> allItems, int currentPage, int pageSize) {
        currentPage = validatePageNumber(currentPage);
        pageSize = validatePageSize(pageSize);

        int totalItems = allItems.size();
        int startIndex = calculateStartIndex(currentPage, pageSize);

        // 判断起始索引是否超过总数
        if (startIndex >= totalItems) {
            return new Page<>(currentPage, pageSize, totalItems, new ArrayList<>());
        }

        // 计算结束索引
        int endIndex = Math.min(startIndex + pageSize, totalItems);
        List<T> pageItems = allItems.subList(startIndex, endIndex);

        return new Page<>(currentPage, pageSize, totalItems, pageItems);
    }
}

PaginationUtils 方法详解

1. 分页结果封装类 Page<T>：

   • Page<T> 类封装了分页的核心信息，包括当前页码、每页大小、总记录数、总页数，以及当前页的数据列表。
   • 提供了必要的构造方法和 getters，便于获取分页信息。

2. 分页参数验证：

   • validatePageNumber(int pageNumber)：验证页码，确保其为正数。小于 1 的页码将被修正为 1。
   • validatePageSize(int pageSize)：验证每页大小，设定默认值（10）和最大值（100），确保分页请求合理。

3. 计算起始索引：

   • calculateStartIndex(int currentPage, int pageSize)：根据当前页码和每页大小计算数据起始索引，用于从数据源获取数据。

4. 获取分页数据：

   • paginate(List<T> allItems, int currentPage, int pageSize)：核心分页方法，根据当前页码和每页大小，从数据源（如列表）中提取相应的分页数据。
   • 方法内部调用参数验证和索引计算函数，返回封装好的分页结果 Page<T>。

应用场景

1. 列表分页显示：

   • 在 Web 应用中，分页显示列表数据是常见需求。PaginationUtils 可以轻松对数据进行分页处理，并返回带有分页信息的结果。
   • 适用于展示用户列表、商品列表、文章列表等大数据集。

2. 数据库查询结果分页：

   • 从数据库查询的大量结果集可以使用 PaginationUtils 进行分页管理。
   • 可配合数据库分页查询（如 LIMIT 和 OFFSET）使用，以减少内存占用并优化查询性能。

3. API 数据分页：

   • 在 API 设计中，分页是标准实践，尤其是对于返回大量数据的端点。
   • 使用 PaginationUtils 可以确保 API 响应的分页一致性，并简化分页逻辑。

4. 数据处理与批量操作：

   • 在批量处理数据时，通过分页可以将大数据集拆分为小块，逐步处理以减少内存压力。
   • 适用于批量导入、批量计算等场景。

使用示例

import java.util.Arrays;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        // 示例数据集
        List<String> items = Arrays.asList(
                "Item1", "Item2", "Item3", "Item4", "Item5",
                "Item6", "Item7", "Item8", "Item9", "Item10",
                "Item11", "Item12", "Item13", "Item14", "Item15"
        );

        // 请求第 2 页，每页显示 5 条数据
        int currentPage = 2;
        int pageSize = 5;

        PaginationUtils.Page<String> page = PaginationUtils.paginate(items, currentPage, pageSize);

        // 输出分页信息
        System.out.println(page);
        page.getItems().forEach(System.out::println);

        // 测试页码参数验证
        PaginationUtils.Page<String> invalidPage = PaginationUtils.paginate(items, -1, 200);
        System.out.println(invalidPage);
    }
}

输出示例

Page 2 of 3, Showing 5 of 15 items
Item6
Item7
Item8
Item9
Item10
Page 1 of 3, Showing 10 of 15 items
Item1
Item2
Item3
Item4
Item5
Item6
Item7
Item8
Item9
Item10

优势与注意事项

1. 优势：

   • PaginationUtils 提供了对分页的全方位封装，简化了分页逻辑，使代码更简洁易读。
   • 通过参数验证机制，可以避免分页请求中的错误，如非法页码和超大分页大小。
   • 支持任意类型的数据列表，灵活应用于各种数据分页需求。

2. 注意事项：

   • 使用分页时，需要确保数据源的顺序性和稳定性，以保持分页结果的一致性。
   • 对于大数据集，建议使用数据库分页查询配合 PaginationUtils，避免内存消耗过高。
   • 在 API 设计中，分页参数应遵循一定规范（如默认页码、最大页大小），确保接口易用性。

进阶与扩展

1. 数据库分页集成：扩展 PaginationUtils，支持直接与数据库查询集成，根据当前页码和每页大小生成 SQL 查询语句。
2. 多条件排序与过滤：结合分页功能，增加多条件排序与过滤功能，适用于更复杂的数据分页展示。
3. 缓存与异步分页：对于极大数据集，可以结合缓存机制和异步分页，优化分页响应时间和资源占用。

结论

PaginationUtils 是一个功能全面的 Java 分页工具类，通过封装常见的分页操作，极大简化了开发中的分页任务。无论是在 Web 应用、API 开发还是数据处理场景中，PaginationUtils 都能够提供高效、简洁的分页解决方案。在实际应用中，通过合理使用 PaginationUtils，开发者可以显著提高