📅 发布时间：2026/6/20 13:06:11

PageHelp插件使用

一、PageHelper 是什么？

PageHelper 是 MyBatis 的一个开源分页插件，它通过拦截 MyBatis 执行的 SQL 语句，自动在原SQL上添加分页语句（如 MySQL 的 LIMIT），并同时查询总记录数。

核心特点：

简单易用：只需要一行代码即可实现分页
支持多种数据库：MySQL、Oracle、PostgreSQL、SQLServer 等
零侵入：不需要修改原有Mapper和SQL语句
功能丰富：支持多种分页方式、排序、Count查询优化等

二、为什么要用 PageHelper？

在没有分页插件时，我们需要手动写分页SQL：

sql

-- 传统方式需要写两条SQL
SELECT COUNT(*) FROM users WHERE age > 18;  -- 查询总数
SELECT * FROM users WHERE age > 18 LIMIT 0, 10;  -- 查询数据

PageHelper 的优势：

代码简洁：一行代码代替复杂的分页逻辑
维护方便：分页逻辑与业务逻辑分离
功能强大：自动处理总数统计、页码计算等
性能优化：支持多种 Count 查询优化策略

三、集成与配置

1. 添加依赖

Maven 项目：

xml

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

Gradle 项目：

gradle

implementation 'com.github.pagehelper:pagehelper-spring-boot-starter:1.4.2'

2. 配置文件（application.yml）

yaml

pagehelper:helper-dialect: mysql  # 数据库方言：mysql, oracle, postgresql 等reasonable: true       # 分页合理化：true时，pageNum<=0会查询第一页，pageNum>总页数会查询最后一页support-methods-arguments: true  # 支持通过Mapper接口参数来传递分页参数params: count=countSql  # 用于从Map或ServletRequest中参数名的映射page-size-zero: false   # 当pageSize=0时返回所有结果

四、核心使用方法

1. 基本分页查询

这是最常用的方式，在查询方法前调用 PageHelper.startPage()：

java

@Service
public class UserService {@Autowiredprivate UserMapper userMapper;/*** 分页查询用户列表*/public PageInfo<User> getUsersByPage(int pageNum, int pageSize) {// 关键代码：在查询方法前调用，第一个参数是页码，第二个是每页大小PageHelper.startPage(pageNum, pageSize);// 正常的查询，不需要任何修改List<User> userList = userMapper.selectAllUsers();// 用PageInfo对结果进行包装，PageInfo包含了丰富的分页信息PageInfo<User> pageInfo = new PageInfo<>(userList);return pageInfo;}
}

2. Mapper 接口和 XML

UserMapper.java:

java

@Mapper
public interface UserMapper {List<User> selectAllUsers();List<User> selectUsersByCondition(UserQuery query);
}

UserMapper.xml:

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.mapper.UserMapper"><!-- 正常的查询SQL，不需要任何分页语句 --><select id="selectAllUsers" resultType="User">SELECT id, name, age, email FROM users</select><select id="selectUsersByCondition" parameterType="UserQuery" resultType="User">SELECT id, name, age, email FROM usersWHERE 1=1<if test="name != null and name != ''">AND name LIKE CONCAT('%', #{name}, '%')</if><if test="minAge != null">AND age >= #{minAge}</if><if test="maxAge != null">AND age <= #{maxAge}</if></select>
</mapper>

3. 实体类

java

// 用户实体
@Data
public class User {private Long id;private String name;private Integer age;private String email;
}// 查询条件实体
@Data
public class UserQuery {private String name;private Integer minAge;private Integer maxAge;
}

五、PageInfo 对象详解

PageInfo 对象包含了完整的分页信息，非常适合返回给前端：

java

// 测试分页查询
@Test
public void testPageInfo() {PageHelper.startPage(2, 5); // 查询第2页，每页5条List<User> userList = userMapper.selectAllUsers();PageInfo<User> pageInfo = new PageInfo<>(userList);// 打印分页信息System.out.println("当前页: " + pageInfo.getPageNum());System.out.println("每页大小: " + pageInfo.getPageSize());System.out.println("当前页数据: " + pageInfo.getList());System.out.println("总记录数: " + pageInfo.getTotal());System.out.println("总页数: " + pageInfo.getPages());System.out.println("是否是第一页: " + pageInfo.isIsFirstPage());System.out.println("是否是最后一页: " + pageInfo.isIsLastPage());System.out.println("是否有上一页: " + pageInfo.isHasPreviousPage());System.out.println("是否有下一页: " + pageInfo.isHasNextPage());
}

PageInfo 常用属性：

list：分页后的数据列表
pageNum：当前页码
pageSize：每页显示数量
total：总记录数
pages：总页数
prePage：上一页页码
nextPage：下一页页码
isFirstPage/isLastPage：是否第一页/最后一页
hasPreviousPage/hasNextPage：是否有上一页/下一页
navigatePages：导航页码数（默认8）
navigatepageNums：所有导航页号

六、多种使用方式

1. 方式一：startPage + PageInfo（推荐）

java

PageHelper.startPage(1, 10);
List<User> list = userMapper.selectByExample(example);
PageInfo<User> pageInfo = new PageInfo<>(list);

2. 方式二：使用Page对象

java

PageHelper.startPage(1, 10);
List<User> list = userMapper.selectByExample(example);
PageInfo<User> pageInfo = new PageInfo<>(list);// 或者直接使用Page对象
Page<User> page = (Page<User>) list;
System.out.println("总数: " + page.getTotal());

3. 方式三：使用Mapper接口参数（需要配置）

java

// 在接口方法中添加RowBounds参数
List<User> selectByRowBounds(UserExample example, RowBounds rowBounds);// 使用
List<User> list = userMapper.selectByRowBounds(example, new RowBounds(0, 10));

七、高级功能

1. 排序功能

java

// 单字段排序
PageHelper.startPage(1, 10, "id desc");// 多字段排序
PageHelper.startPage(1, 10, "age asc, name desc");// 或者使用OrderBy
PageHelper.startPage(1, 10).setOrderBy("create_time desc");

2. 复杂查询条件 + 分页

java

public PageInfo<User> searchUsers(UserQuery query, int pageNum, int pageSize) {PageHelper.startPage(pageNum, pageSize);List<User> userList = userMapper.selectUsersByCondition(query);return new PageInfo<>(userList);
}

3. 只分页不查询总数（提升性能）

java

// 第三个参数设为false，不执行count查询
PageHelper.startPage(1, 10, false);
List<User> list = userMapper.selectAllUsers();

八、完整实战示例

1. Controller 层

java

@RestController
@RequestMapping("/api/users")
public class UserController {@Autowiredprivate UserService userService;/*** 分页查询用户列表*/@GetMappingpublic Result<PageInfo<User>> getUsers(@RequestParam(defaultValue = "1") int pageNum,@RequestParam(defaultValue = "10") int pageSize,@RequestParam(required = false) String name,@RequestParam(required = false) Integer minAge,@RequestParam(required = false) Integer maxAge) {UserQuery query = new UserQuery();query.setName(name);query.setMinAge(minAge);query.setMaxAge(maxAge);PageInfo<User> pageInfo = userService.searchUsers(query, pageNum, pageSize);return Result.success(pageInfo);}
}// 统一返回结果封装
@Data
class Result<T> {private int code;private String message;private T data;public static <T> Result<T> success(T data) {Result<T> result = new Result<>();result.setCode(200);result.setMessage("success");result.setData(data);return result;}
}

2. Service 层

java

@Service
public class UserService {@Autowiredprivate UserMapper userMapper;public PageInfo<User> searchUsers(UserQuery query, int pageNum, int pageSize) {// 开启分页PageHelper.startPage(pageNum, pageSize);// 执行查询List<User> userList = userMapper.selectUsersByCondition(query);// 返回分页结果return new PageInfo<>(userList);}
}

3. 前端调用示例

http

GET /api/users?pageNum=2&pageSize=5&name=张&minAge=18

4. 返回结果示例

json

{"code": 200,"message": "success","data": {"pageNum": 2,"pageSize": 5,"total": 23,"pages": 5,"list": [{"id": 6,"name": "张三","age": 25,"email": "zhangsan@example.com"},// ... 其他4条数据],"prePage": 1,"nextPage": 3,"isFirstPage": false,"isLastPage": false,"hasPreviousPage": true,"hasNextPage": true}
}

九、注意事项

确保 PageHelper.startPage() 后紧跟查询语句

java

// ✅ 正确
PageHelper.startPage(1, 10);
List<User> list = userMapper.selectAll();// ❌ 错误：中间不能有其他代码
PageHelper.startPage(1, 10);
System.out.println("开始查询"); // 这行代码会导致分页失效
List<User> list = userMapper.selectAll();

线程安全：PageHelper 基于 ThreadLocal，确保在同一个线程内使用

Count查询优化：对于复杂查询，可以自定义Count查询

xml

<select id="selectWithCustomCount" resultType="User">SELECT * FROM users WHERE ...
</select><select id="selectWithCustomCount_COUNT" resultType="long">SELECT COUNT(*) FROM users WHERE ...
</select>

总结

PageHelper 是一个非常强大且易用的 MyBatis 分页插件，通过简单的 PageHelper.startPage() 调用，就可以实现完整的分页功能。它的主要优点在于：

使用简单：一行代码实现分页
功能丰富：支持排序、多种分页方式等
兼容性好：支持多种数据库
性能优秀：提供Count查询优化

掌握了 PageHelper 的使用，可以极大提高开发效率和代码质量。建议多动手实践，很快就能熟练掌握！