从七年开发视角带你吃透 Spring Boot 整合 Pagehelper（附全流程实战 + 工具类）​

从七年开发视角带你吃透 Spring Boot 整合 Pagehelper（附全流程实战 + 工具类）

在 Java Web 开发领域摸爬滚打七年，深知分页功能在项目中的重要性。无论是处理海量数据的后台管理系统，还是追求用户体验的前端页面，分页都是优化数据展示、提升性能的关键手段。Spring Boot 作为当下流行的 Java 开发框架，以其简洁高效的特性深受开发者喜爱；Pagehelper 则是一款强大的 MyBatis 分页插件，二者结合，能极大简化分页开发流程。本文将凭借七年积累的经验，深入剖析 Spring Boot 整合 Pagehelper 的全过程，涵盖原理、实战及工具类封装，助力大家快速掌握这一核心技能。

一、为什么选择 Pagehelper 实现分页

在深入整合之前，先谈谈为何 Pagehelper 能从众多分页方案中脱颖而出。在早期开发中，手动编写分页 SQL 是常态，这意味着要精准计算偏移量、控制每页数据量，稍有不慎就会出错。不同数据库分页语法还存在差异，像 MySQL 用 LIMIT，Oracle 用 ROWNUM，维护多套分页 SQL 让开发成本直线上升。后来虽有一些框架自带分页功能，但灵活性欠佳，难以适配复杂业务场景。

Pagehelper 的出现完美解决了这些痛点。它基于 MyBatis 拦截器机制，在 SQL 执行前自动添加分页逻辑，开发者只需简单配置，就能实现强大分页功能，大大提高开发效率。而且它支持多种数据库，无论是常见的 MySQL、Oracle，还是 SQL Server 等，都能无缝适配，真正做到一处配置，多处使用。

二、Spring Boot 整合 Pagehelper 全流程实战

（一）引入依赖

开始整合，第一步是在 Spring Boot 项目的 pom.xml 文件中引入 Pagehelper 相关依赖。如果项目使用 Maven 构建，添加如下依赖：

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>1.4.7</version> <!-- 可根据实际情况选择最新版本 -->
</dependency>

该依赖会自动引入 Pagehelper 核心库及相关依赖，为后续配置和使用奠定基础。

（二）配置 Pagehelper

1. YAML 配置

在 application.yml 文件中进行 Pagehelper 基础配置，示例如下：

pagehelper:
  helper-dialect: mysql # 指定数据库方言，这里以MySQL为例，支持多种数据库
  reasonable: true # 分页合理化，当页码<1时查询第一页，页码>总页数时查询最后一页
  support-methods-arguments: true # 支持通过Mapper接口参数传递分页参数
  params: count=countSql # 指定count查询的参数名称

helper-dialect 至关重要，它告诉 Pagehelper 使用哪种数据库分页语法；reasonable 让分页更人性化；support-methods-arguments 方便在 Mapper 接口中灵活传参；params 配置则用于优化 count 查询。

2. Java 配置类（可选）

除了 YAML 配置，也可通过 Java 配置类进行配置，适合习惯 Java 代码配置的开发者。创建一个配置类，示例如下：

import com.github.pagehelper.PageHelper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Properties;
@Configuration
public class PageHelperConfig {
    @Bean
    public PageHelper pageHelper() {
        PageHelper pageHelper = new PageHelper();
        Properties properties = new Properties();
        properties.setProperty("helperDialect", "mysql");
        properties.setProperty("reasonable", "true");
        properties.setProperty("supportMethodsArguments", "true");
        properties.setProperty("params", "count=countSql");
        pageHelper.setProperties(properties);
        return pageHelper;
    }
}

两种配置方式效果相同，任选其一即可。

（三）编写 Mapper 接口和 XML 文件

假设项目中有一个用户表 users，要实现用户数据分页查询。首先定义 Mapper 接口 UserMapper：

import com.example.demo.entity.User;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Select;
import java.util.List;
@Mapper
public interface UserMapper {
    @Select("SELECT * FROM users")
    List<User> selectAllUsers();
}

接着编写对应的 Mapper XML 文件 UserMapper.xml：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.demo.mapper.UserMapper">
    <select id="selectAllUsers" resultType="com.example.demo.entity.User">
        SELECT * FROM users
    </select>
</mapper>

这里的 SQL 语句可根据实际业务需求进行复杂查询，Pagehelper 会自动为其添加分页逻辑。

（四）在 Service 层使用 Pagehelper

在 Service 层调用 Mapper 接口进行分页查询。创建 UserService 类，示例如下：

import com.github.pagehelper.PageHelper;
import com.github.pagehelper.PageInfo;
import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class UserService {
    private final UserMapper userMapper;
    public UserService(UserMapper userMapper) {
        this.userMapper = userMapper;
    }
    public PageInfo<User> getUsers(int pageNum, int pageSize) {
        PageHelper.startPage(pageNum, pageSize);
        List<User> users = userMapper.selectAllUsers();
        return new PageInfo<>(users);
    }
}

关键代码 PageHelper.startPage(pageNum, pageSize) 用于设置分页参数，pageNum 为页码，pageSize 为每页数据量。执行该语句后，后续的查询会自动带上分页逻辑，PageInfo 则封装了分页后的结果，包括总页数、总记录数、当前页数据等信息。

（五）Controller 层调用

**

最后在 Controller 层通过 RESTful 接口对外提供分页查询服务。创建 UserController 类，示例如下：

import com.github.pagehelper.PageInfo;
import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
    private final UserService userService;
    public UserController(UserService userService) {
        this.userService = userService;
    }
    @GetMapping("/users")
    public PageInfo<User> getUsers(
            @RequestParam(defaultValue = "1") int pageNum,
            @RequestParam(defaultValue = "10") int pageSize) {
        return userService.getUsers(pageNum, pageSize);
    }
}

通过 @RequestParam 注解接收前端传来的页码和每页数据量参数，默认第一页显示 10 条数据。调用 UserService 的 getUsers 方法，将分页结果返回给前端。

至此，Spring Boot 整合 Pagehelper 实现分页查询的全流程实战完成，启动项目，访问 /users 接口，就能看到分页后的用户数据。

三、封装分页工具类，提升开发效率

在实际项目中，为了进一步提高开发效率，减少重复代码，可将分页相关操作封装成工具类。以下是一个简单的分页工具类示例：

import com.github.pagehelper.PageHelper;
import com.github.pagehelper.PageInfo;
import java.util.List;
public class PageUtil {
    /**
     * 开始分页
     * @param pageNum 页码
     * @param pageSize 每页数据量
     */
    public static void startPage(int pageNum, int pageSize) {
        PageHelper.startPage(pageNum, pageSize);
    }
    /**
     * 构建分页结果
     * @param list 数据列表
     * @param <T> 数据类型
     * @return 分页信息对象
     */
    public static <T> PageInfo<T> buildPageInfo(List<T> list) {
        return new PageInfo<>(list);
    }
}

在 Service 层使用时，代码可简化为：

import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import com.example.demo.util.PageUtil;
import com.github.pagehelper.PageInfo;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
public class UserService {
    private final UserMapper userMapper;
    public UserService(UserMapper userMapper) {
        this.userMapper = userMapper;
    }
    public PageInfo<User> getUsers(int pageNum, int pageSize) {
        PageUtil.startPage(pageNum, pageSize);
        List<User> users = userMapper.selectAllUsers();
        return PageUtil.buildPageInfo(users);
    }
}

这样，在多个业务模块需要分页时，直接调用工具类方法，让代码更简洁、易维护。

四、总结与拓展

通过以上步骤，我们从基础原理到全流程实战，深入学习了 Spring Boot 整合 Pagehelper 的方法，并通过封装工具类提升了开发效率。在实际项目中，还可根据业务需求对 Pagehelper 进行更多拓展，如自定义分页参数、优化 count 查询性能等。

同时，要注意 Pagehelper 在不同数据库、不同 Spring Boot 版本下的兼容性问题。随着技术发展，Pagehelper 也在不断更新迭代，建议关注官方文档，及时掌握新特性和最佳实践。希望本文能帮助大家在项目中熟练运用 Spring Boot 与 Pagehelper，高效实现分页功能，提升项目整体性能和用户体验。