使用 PageHelper 在 Spring Boot 项目中实现分页查询

前言

在 Web 应用开发中，分页查询是非常常见的需求，特别是在涉及大量数据的应用场景中，通过分页可以减少数据加载压力，提升系统性能。然而，手动实现分页查询需要编写繁琐的 SQL 语句和逻辑代码，容易出现错误。为了简化分页实现，我们可以借助 PageHelper 这一优秀的分页插件，它能够无缝整合进 Spring Boot 项目，快速实现分页功能。本文将详细介绍如何在 Spring Boot 中整合 PageHelper，并通过示例演示如何进行分页查询。

1. 项目环境配置

1.1 添加 PageHelper 依赖

首先，在 Spring Boot 项目中的 pom.xml 文件中添加 PageHelper 的依赖项。本文使用 pagehelper-spring-boot-starter 作为依赖包，该依赖能够自动配置 PageHelper，减少手动配置的复杂性。以下是 Maven 依赖的示例：

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>1.4.6</version>
</dependency>

添加依赖后，PageHelper 将会自动被 Spring Boot 扫描并加载到上下文中，无需额外配置。此处的 1.4.6 版本适用于 Spring Boot 2.0+ 版本，如果使用其他版本的 Spring Boot，确保选择兼容的 PageHelper 版本。

1.2 数据库和 MyBatis 配置

在 application.yml 中，完成数据库的基本配置，并确认已经集成了 MyBatis。以下是一个基础的数据库配置示例：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/testdb
    username: root
    password: password
    driver-class-name: com.mysql.cj.jdbc.Driver
  mybatis:
    mapper-locations: classpath:mapper/*.xml

2. 统一的分页响应类

为了方便返回分页数据并使返回结果具有一致性，可以定义一个统一的分页响应类。例如，定义一个 PageResponse<T> 类，该类包含总页数、总条数、当前页数据等信息。

public class PageResponse<T> {
    private long total;       // 总记录数
    private int pages;        // 总页数
    private List<T> data;     // 当前页数据

    public PageResponse(long total, int pages, List<T> data) {
        this.total = total;
        this.pages = pages;
        this.data = data;
    }

    // Getters and Setters
}

在实际使用中，通过 PageHelper 查询得到的 PageInfo 对象中包含分页信息，可以将其数据提取并填充到 PageResponse 中，以统一格式返回。

3. 使用 PageHelper 实现分页查询

在配置好依赖和基础环境后，接下来在 Service 层中使用 PageHelper 实现分页查询。假设有一个 UserService 用于处理用户数据查询，可以按以下步骤实现分页功能。

3.1 Service 层分页查询实现

PageHelper 的分页逻辑非常简单，只需在查询方法中通过 PageHelper.startPage(pageNum, pageSize) 设置分页参数，接着调用查询方法，即可获得分页结果。以下示例展示了 UserService 的实现：

@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;

    public PageResponse<User> getUsers(int pageNum, int pageSize) {
        PageHelper.startPage(pageNum, pageSize);   // 设置分页参数
        List<User> userList = userMapper.selectAll();  // 执行查询
        PageInfo<User> pageInfo = new PageInfo<>(userList); // 使用PageInfo包装分页结果

        // 使用PageResponse返回统一分页格式
        return new PageResponse<>(pageInfo.getTotal(), pageInfo.getPages(), pageInfo.getList());
    }
}

在 getUsers() 方法中，首先通过 PageHelper.startPage() 设置分页参数，随后调用 selectAll() 执行数据库查询。PageHelper 会拦截该查询并自动添加分页 SQL，返回的 userList 为分页结果，然后用 PageInfo 包装查询结果。

3.2 PageHelper 分页注意事项

1. startPage 方法的调用位置：PageHelper.startPage(pageNum, pageSize) 必须在查询方法之前调用，否则分页信息将不会生效。
2. 自动分页结果类型：selectAll() 返回的 userList 实际上是 Page 类型的 List，Page 实现了 List 接口，因此可以正常操作。但直接强制转换为 Page 可能会导致错误，正确的方式是将结果用 PageInfo 包装。
3. 版本兼容性问题：如果使用 PageHelper 版本与 Spring Boot 不兼容，可能会导致分页信息不正确。确保选择正确的版本，如 PageHelper 1.4.6 与 Spring Boot 2.0+ 兼容性良好。

4. 控制层调用示例

在控制器层调用 UserService 的 getUsers() 方法，并将 PageResponse 数据返回给前端。以下是一个简单的控制层示例：

@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;

    @GetMapping("/page")
    public ResponseEntity<PageResponse<User>> getUsers(@RequestParam int pageNum, @RequestParam int pageSize) {
        PageResponse<User> pageResponse = userService.getUsers(pageNum, pageSize);
        return ResponseEntity.ok(pageResponse);
    }
}

通过 @GetMapping("/page") 实现分页查询接口，前端可以通过传递 pageNum 和 pageSize 参数来控制分页查询的页码和每页数量。

5. 常见问题与解决方案

5.1 java.util.ArrayList cannot be cast to com.github.pagehelper.Page

出现此异常的原因通常是因为尝试将 ArrayList 强制转换为 Page 类型。实际上，分页查询返回的 List 是 Page 的实例，但我们不应该直接进行类型转换，而是通过 PageInfo 进行包装，这样可以避免强制转换带来的问题。

5.2 分页参数未生效，返回全部数据

如果 PageHelper 无法获取正确的分页参数，导致返回所有数据，可能是以下原因之一：

• 版本兼容性问题：确保 PageHelper 和 Spring Boot 的版本兼容。推荐 PageHelper 1.4.6 版本与 Spring Boot 2.0+。
• 调用顺序问题：PageHelper.startPage() 必须在查询数据库之前调用，否则分页不会生效。

通过确认上述设置，基本可以解决分页参数未生效的问题。

结语

在 Spring Boot 项目中整合 PageHelper 可以大大简化分页查询的实现。本文详细介绍了 PageHelper 的配置方法、Service 层分页查询的实现步骤，以及常见问题的解决方法。通过 PageHelper，我们可以方便地对数据库数据进行分页处理，提升系统的查询效率和用户体验。希望本文内容能为大家在实际开发中带来帮助。