1. 项目概述为什么我们需要一个“聪明”的分页插件如果你用MyBatis做过稍微复杂点的列表查询肯定对分页这件事又爱又恨。爱的是数据分页是几乎所有Web应用的标配能极大提升用户体验和系统性能恨的是手动实现分页太繁琐了。你得在SQL里写LIMIT ?, ?还得额外查一次总数COUNT(*)业务代码里要计算页码、页大小把参数传给Mapper最后再把查询结果和总数包装成一个分页对象返回。一套流程下来重复代码一大堆还容易出错。PageHelper就是为了终结这种繁琐而生的。它不是一个独立的新框架而是一个无缝集成到MyBatis中的分页插件。它的核心思想非常巧妙通过拦截MyBatis执行的SQL语句在运行时动态地为你补上分页逻辑。你只需要在查询之前简单地调用一句PageHelper.startPage(pageNum, pageSize)那么紧随其后的第一个MyBatis查询方法就会自动被改造为分页查询。它帮你处理了所有底层细节重写SQL、查询总数、封装结果。而PageInfo则是PageHelper查询结果的“豪华包装器”它不仅包含了当前页的数据列表还附赠了总页数、总记录数、是否是第一页/最后一页、前后页码等一大堆你在前端分页组件里急需的信息。简单来说PageHelper让你从“手工计算分页参数并执行两条SQL”的原始时代一步跨入“声明式分页”的自动化时代。它特别适合快速开发的场景无论是管理后台、数据报表还是API接口都能让你用最少的代码实现最标准、最健壮的分页功能。接下来我会结合自己多年的使用和踩坑经验带你彻底吃透这个工具。2. 核心原理与设计思路拆解它到底是怎么“拦截”SQL的要用好一个工具最好先理解它背后的工作原理。PageHelper的魔力源于MyBatis提供的插件Interceptor机制。我们可以把MyBatis执行SQL的过程想象成一条流水线解析Mapper接口 - 获取SQL语句 - 设置参数 - 执行SQL - 处理结果。插件就像在这条流水线上安装的“智能关卡”可以在特定环节对流程进行干预。2.1 MyBatis插件机制与拦截点PageHelper实现了一个Interceptor接口并指定它拦截Executor类的query方法。Executor是MyBatis的核心执行器所有数据库查询操作最终都由它来完成。当你的代码调用Mapper.selectList()时调用链会经过这个被插件增强的Executor。插件的核心方法是intercept。PageHelper在这里面做了以下几件关键事判断是否需要分页检查当前线程上下文中是否存在分页参数即你是否调用了PageHelper.startPage。如果没有直接放行执行原始查询。获取原始SQL并改造如果需要分页它会从MappedStatement中拿到你写在XML或注解里的原始SQL。然后根据数据库方言Dialect将原始SQL改造成分页查询SQL。例如对于MySQL它会把SELECT * FROM user在运行时动态转换为SELECT * FROM user LIMIT 0, 10并同时生成一条计算总数的SQLSELECT COUNT(0) FROM user。执行改造后的SQL它先执行计算总数的SQL得到总记录数total。然后再执行加入了LIMIT的分页查询SQL得到当前页的数据列表list。封装结果最后它将list和total封装到一个Page对象中并返回。这个Page对象本身也实现了List接口所以你的业务代码感知不到变化依然按List来接收但实际上它已经“内涵”了分页信息。2.2 基于ThreadLocal的上下文传递这里有一个精妙的设计分页参数页码、页大小是如何从你调用PageHelper.startPage()的地方传递到插件内部的呢答案是ThreadLocal。ThreadLocal可以理解为每个线程独有的一个变量储物柜。当你调用PageHelper.startPage(1, 10)时它会把页码1和页大小10存入当前线程的ThreadLocal储物柜中。随后当这个线程执行MyBatis查询时PageHelper插件再从同一个ThreadLocal储物柜里把参数取出来使用。用完后插件会自动清理这个储物柜确保分页参数不会污染下一次查询。重要心得理解ThreadLocal机制是避免分页失效或混乱的关键。这意味着分页参数是线程绑定的且一次有效。如果你在调用startPage后没有立即执行查询或者在一个线程里多次查询却只想分页一次就需要格外小心。2.3 为什么选择PageHelper方案对比除了PageHelper分页还有几种常见方案手写SQL如前所述繁琐、易错、难维护。MyBatis-Plus分页MyBatis-Plus是MyBatis的增强工具其分页功能同样强大。它与PageHelper的主要区别在于集成方式。MP的分页需要配置一个PaginationInterceptor插件并且在Service层使用其提供的Page对象和selectPage方法与MP的Wrapper查询条件结合更紧密。如果你整个项目都用MP那用它的分页是更一致的选择。Spring Data JPA分页如果你是JPA技术栈那么Pageable和Page对象是标准方案与Repository集成度极高。PageHelper的优势在于对原生MyBatis的无侵入和极简使用。你不需要改变现有的MyBatis Mapper和Service的写法只需在查询前加一行代码。这对于改造遗留项目或者在不想引入MP等全套增强功能的项目中显得非常轻量和友好。3. 环境配置与集成详解从引入到生效的每一步理论懂了我们动手把它集成到项目里。这里以最主流的Spring Boot项目为例演示完整的集成过程。3.1 依赖引入首先在项目的pom.xml中添加依赖。请注意版本兼容性建议使用较新的稳定版。dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.6/version !-- 请检查最新版本 -- /dependency使用pagehelper-spring-boot-starter是最省事的方式。这个Starter会自动完成插件的配置和Bean的注册你不需要再手动写任何XML配置。如果你用的是非Spring Boot的SSM项目则需要引入pagehelper依赖并在mybatis-config.xml中手动配置插件。3.2 基础配置application.yml虽然Starter提供了自动配置但为了满足不同需求我们通常需要在application.yml中进行一些定制。下面是一个常用配置示例pagehelper: helper-dialect: mysql # 指定数据库方言这是最重要的配置 reasonable: true # 启用“合理化”参数。当pageNum0时查询第一页当pageNum总页数时查询最后一页。 support-methods-arguments: true # 支持通过Mapper接口参数来传递分页参数 params: countcountSql # 用于配置count查询的SQL映射 page-size-zero: true # 当pageSize0时返回所有结果相当于没分页配置项深度解析helper-dialect: 必须正确配置。它告诉PageHelper你的数据库类型以便生成正确的分页SQLMySQL用LIMITOracle用ROWNUM等。如果配置错误会导致生成的SQL语法错误。reasonable: 我个人强烈建议开启。这是一个非常贴心的功能。假设总共有5页用户输入了页码-1或100开启后会自动修正为第1页或第5页而不是返回空数据或抛出异常对用户体验和系统健壮性都有好处。support-methods-arguments: 这个配置允许你像这样使用分页PageUser selectByCondition(Param(“condition”) Condition cond, Param(“pageNum”) int pageNum, Param(“pageSize”) int pageSize)然后在XML中可以通过#{pageNum}和#{pageSize}获取参数。这是一种更“显式”的分页方式但不如startPage常用。3.3 验证配置是否生效配置完成后如何验证插件已经正确工作了呢一个简单的方法是查看启动日志或者写一个简单的测试。更直接的方法是开启MyBatis的SQL日志打印观察执行的SQL语句是否被改写。在application.yml中配置logging: level: com.yourmapper.package: debug # 将你的Mapper包路径设为DEBUG级别执行一个分页查询你会在日志中看到两条SQLDEBUG - Preparing: SELECT count(0) FROM user WHERE age ? DEBUG - Parameters: 18(Integer) DEBUG - Preparing: SELECT * FROM user WHERE age ? LIMIT ?, ? DEBUG - Parameters: 18(Integer), 0(Integer), 10(Integer)看到COUNT语句和带LIMIT的语句就证明PageHelper已经成功拦截并改造了SQL。4. 核心使用方式与PageInfo详解配置妥当我们来看看怎么用。PageHelper的使用核心就一句话但围绕这句话的细节和其产出的PageInfo对象才是体现功力的地方。4.1 基础用法PageHelper.startPage这是最经典、最常用的方式。在Service层或任何执行MyBatis查询的地方在查询方法之前调用。Service public class UserServiceImpl implements UserService { Autowired private UserMapper userMapper; Override public PageInfoUser getUsersByPage(int pageNum, int pageSize) { // 关键代码在此行之后第一次执行的MyBatis查询会自动分页 PageHelper.startPage(pageNum, pageSize); // 执行查询。这个List已经不是普通的ArrayList而是PageHelper内置的Page对象 ListUser userList userMapper.selectAllUsers(); // 将查询结果用PageInfo包装PageInfo包含了非常全面的分页信息 PageInfoUser pageInfo new PageInfo(userList); return pageInfo; } }必须注意的执行顺序PageHelper.startPage(pageNum, pageSize)必须紧挨着MyBatis查询语句之前调用。它们之间不能有其它数据库查询操作否则分页参数可能会被意外的查询消耗掉导致你的目标查询不分页或者为其它查询错误地加上分页。4.2 PageInfo分页信息的“瑞士军刀”直接返回ListUser给前端前端还得自己算总页数、是否有下一页太麻烦了。PageInfo就是用来解决这个问题的。它把分页的所有相关信息都打包好了。我们来看看PageInfo对象里有哪些宝贝以下属性在创建PageInfo后可直接获取// 创建PageInfo PageInfoUser pageInfo new PageInfo(userList); // 核心属性 pageInfo.getList(); // 当前页的数据列表就是传入的userList pageInfo.getTotal(); // 总记录数非常重要用于计算总页数 pageInfo.getPageNum(); // 当前页码 pageInfo.getPageSize(); // 每页显示条数 pageInfo.getPages(); // 总页数由total和pageSize计算得出 pageInfo.isIsFirstPage(); // 是否是第一页 pageInfo.isIsLastPage(); // 是否是最后一页 pageInfo.hasPreviousPage(); // 是否有上一页 pageInfo.hasNextPage(); // 是否有下一页 // 导航页码相关非常适用于生成前端页码栏 pageInfo.getNavigatePages(); // 导航栏显示的页码数量可配置默认8 pageInfo.getNavigatepageNums(); // 所有导航页的页码数组如[1,2,3,4,5] pageInfo.getPrePage(); // 上一页的页码 pageInfo.getNextPage(); // 下一页的页码前端对接示例在前后端分离项目中你可以直接将PageInfo对象序列化成JSON返回给前端。前端拿到后list用于渲染表格pageNum,pageSize,total,pages等属性直接用于配置分页组件如Element UI的Pagination几乎无需额外计算。4.3 高级用法与链式调用PageHelper也支持更灵活的链式调用可以在startPage的同时设置更多参数。// 链式调用设置页码、页大小并开启count查询默认就是开启的 PageHelper.startPage(pageNum, pageSize).count(true); // 更复杂的场景如果你只想分页但不想执行耗时的count查询比如在数据量极大时count非常慢 PageHelper.startPage(pageNum, pageSize, false); // 第三个参数设为false不进行count查询 ListUser userList userMapper.selectAllUsers(); // 此时如果你还用 new PageInfo(userList)里面的getTotal()是错的因为它拿不到总数。 // 这种情况下通常直接返回List和“是否有下一页”的标识。可以通过判断返回的list.size()是否等于pageSize来推测。什么情况下关闭count查询在无限滚动上拉加载更多的场景下前端通常不需要知道数据总量只需要判断“是否还有下一页”。此时可以先请求pageSize1条数据如果返回的数据量大于pageSize则说明还有下一页当前页只展示pageSize条并隐藏多余的那一条作为探测。这样可以避免大数据量表下COUNT(*)的性能瓶颈。5. 复杂场景下的实战与避坑指南在实际项目中分页很少是简单的SELECT *。更多是伴随着多表关联、复杂条件筛选和排序。PageHelper在这些场景下表现如何又有哪些坑需要注意5.1 多表关联查询与性能陷阱这是PageHelper最容易出问题的地方。假设我们有一个用户(user)表和订单(order)表要分页查询用户及其订单列表。错误示范导致分页结果不准!-- UserMapper.xml -- select idselectUserWithOrders resultMapuserWithOrdersMap SELECT u.*, o.order_id, o.amount FROM user u LEFT JOIN order o ON u.id o.user_id WHERE u.status 1 ORDER BY u.create_time DESC /select问题在于如果一个用户有3个订单JOIN查询后这个用户会在结果集中出现3次。PageHelper的COUNT查询是基于这个完整的JOIN后的结果集进行的。假设一页10条可能第1页只显示了4个用户因为他们总共有10个订单但COUNT查询的总数却是“订单行数”而不是“用户数”。这会导致总页数计算错误分页逻辑混乱。解决方案子查询分页推荐先分页查询出主表用户的ID再用这些ID去关联查询从表订单。select idselectUserWithOrders resultMapuserWithOrdersMap SELECT u.*, o.order_id, o.amount FROM user u LEFT JOIN order o ON u.id o.user_id WHERE u.id IN ( !-- 先分页查出用户ID -- SELECT id FROM user WHERE status 1 ORDER BY create_time DESC LIMIT #{offset}, #{pageSize} ) ORDER BY u.create_time DESC /select这种方式需要你手动计算offset失去了PageHelper的自动分页便利但逻辑最清晰性能也更好特别是user表有索引时。使用PageHelper的count查询优化PageHelper允许你为复杂的count查询单独指定一个更简单的SQL。这需要较复杂的配置且对SQL编写要求高不推荐新手使用。核心避坑点PageHelper的分页逻辑是物理分页在数据库层面用LIMIT截取数据。对于多对一如查询文章和作者的关联它工作良好。但对于一对多如查询用户和订单的关联直接在JOIN的SQL上使用PageHelper分页的主体对象用户数量会不准。务必先确定分页的“主体”并围绕主体设计查询。5.2 排序Order By与分页的配合排序是分页查询的好搭档但需要注意顺序。PageHelper.startPage(pageNum, pageSize); // 排序必须在startPage之后且格式有要求 PageHelper.orderBy(create_time DESC, id ASC); ListUser list userMapper.selectByExample(example);PageHelper.orderBy()方法接收的字符串就是SQL中ORDER BY后面的部分。特别注意PageHelper.orderBy()设置的是最终执行SQL的排序它可能会与你XML中写的ORDER BY子句冲突或叠加造成混乱。更清晰、更推荐的做法是将排序逻辑直接写在XML的SQL语句中。5.3 与MyBatis动态SQL如if标签的协作PageHelper与MyBatis的动态SQL协作是天衣无缝的。因为插件是在MyBatis构建完最终的SQL语句之后才进行拦截和改写的。所以无论你的XML里用了多少if、choose标签来动态拼接条件PageHelper都能正确地对最终生成的SQL进行分页处理完全不用担心。5.4 在事务方法中的使用这是一个非常隐蔽的坑。考虑以下代码Transactional public void someBusinessMethod() { // 业务逻辑A... PageHelper.startPage(1, 10); ListUser list1 userMapper.selectA(); // 查询1 // ... 更多业务逻辑 ListOrder list2 orderMapper.selectB(); // 查询2 }在同一个事务方法中如果你在查询1后没有清空分页参数那么查询2也会被分页因为PageHelper使用ThreadLocal存储参数而Spring的事务管理通常会让同一个线程执行整个Transactional方法。解决方法PageHelper提供了一个安全清除线程上下文的方法。在每次分页查询后如果后续还有不希望分页的查询应该手动清理。PageHelper.startPage(1, 10); ListUser list1 userMapper.selectA(); // 清理分页参数防止影响后续查询 PageHelper.clearPage(); ListOrder list2 orderMapper.selectB(); // 这次不会被分页了养成好习惯在确定只需要一次分页的场景下查询完成后立即调用PageHelper.clearPage()。6. 常见问题排查与性能优化技巧即使理解了原理实战中还是会遇到各种奇怪的问题。这里我整理了一份“急救手册”。6.1 问题排查速查表问题现象可能原因解决方案分页完全不生效1.PageHelper.startPage()在查询之后调用。2.PageHelper.startPage()与查询语句之间有其他数据库查询。3. 依赖或配置错误插件未成功加载。1. 确保startPage紧邻目标查询之前。2. 检查中间是否有其他Mapper调用。3. 检查日志确认PageHelper插件已加载检查helper-dialect配置。分页结果混乱总数不对1. SQL是多表JOIN且为一对多关系见5.1节。2. SQL中包含GROUP BYCOUNT查询结果不是期望的行数。1. 重构SQL使用子查询先分页主体。2. 考虑关闭本次查询的count或重写count查询。抛出SQL语法错误helper-dialect配置错误生成了不适用于当前数据库的SQL。检查并修正application.yml中的pagehelper.helper-dialect配置。线程安全问题A请求的分页参数影响了B请求分页参数未及时清理且请求处理使用了线程池如Tomcat线程池线程被复用。1. 确保每次分页查询后在finally块中调用PageHelper.clearPage()。2. 使用PageHelper的Page对象它实现了Closeable配合try-with-resources语法自动清理。COUNT查询非常慢表数据量巨大且查询条件复杂没有合适的索引。1. 为WHERE条件和ORDER BY字段添加索引。2. 如非必要关闭count查询startPage(pageNum, pageSize, false)。3. 考虑使用估算行数或缓存总条数。6.2 性能优化建议索引是王道分页查询的性能瓶颈往往在ORDER BY和WHERE条件上而不是LIMIT本身。确保排序字段和常用查询条件字段上有合适的索引。对于ORDER BY create_time DESC LIMIT N这类查询对create_time建立索引是必须的。避免大偏移量OffsetLIMIT 1000000, 20这种查询MySQL需要先扫描前100万条记录然后扔掉它们再取20条效率极低。对于深度分页业务上限制不允许跳转到太靠后的页或者用“下一页”代替精确页码。使用“游标”或“seek方法”记录上一页最后一条记录的ID或排序字段值下一页查询用WHERE id last_id LIMIT 20。这需要业务逻辑配合且排序字段必须唯一。审慎使用count(1)PageHelper默认使用count(0)或count(1)。在MySQL中count(*)经过优化通常是最快的。你可以通过pagehelper.count-sql配置项自定义COUNT查询例如设置为count(*)。监控与日志在生产环境关注慢SQL日志。如果发现分页查询慢要具体分析是COUNT慢还是主查询慢然后对症下药。6.3 关于MyBatis-Plus分页的补充对比很多同学会纠结用PageHelper还是MyBatis-Plus的分页。这里再清晰对比一下PageHelper优势是简单、直接、无侵入。适合原生MyBatis项目或只需要分页这一项增强功能的场景。它的“魔法”来自于线程上下文拦截理解其原理对避坑很重要。MyBatis-Plus分页优势是功能整合、风格统一。MP的分页是其整个CRUD增强体系的一部分与它的QueryWrapper、UpdateWrapper等条件构造器配合使用非常流畅。如果你已经在使用MP的BaseMapper、Service等全套功能那么继续使用它的分页是更自然的选择。MP的分页配置也是一个Interceptor但使用方式是在Service层传入一个Page对象。选择哪一个取决于你的项目技术栈和团队习惯。对于新项目如果确定会用到MP的多种增强功能直接上MP是更全面的选择。如果只是老项目加个分页或者想保持框架的轻量PageHelper是绝佳的利器。最后再强调一个我踩过多次的坑永远记得PageHelper.startPage()只对其后第一个MyBatis查询生效并且要注意在事务方法或线程复用场景下及时清理。把这个原则刻在脑子里能解决90%的奇怪问题。工具虽好理解了它的脾气才能用得顺手。 MyBatis分页插件PageHelper核心原理、实战应用与避坑指南
1. 项目概述为什么我们需要一个“聪明”的分页插件如果你用MyBatis做过稍微复杂点的列表查询肯定对分页这件事又爱又恨。爱的是数据分页是几乎所有Web应用的标配能极大提升用户体验和系统性能恨的是手动实现分页太繁琐了。你得在SQL里写LIMIT ?, ?还得额外查一次总数COUNT(*)业务代码里要计算页码、页大小把参数传给Mapper最后再把查询结果和总数包装成一个分页对象返回。一套流程下来重复代码一大堆还容易出错。PageHelper就是为了终结这种繁琐而生的。它不是一个独立的新框架而是一个无缝集成到MyBatis中的分页插件。它的核心思想非常巧妙通过拦截MyBatis执行的SQL语句在运行时动态地为你补上分页逻辑。你只需要在查询之前简单地调用一句PageHelper.startPage(pageNum, pageSize)那么紧随其后的第一个MyBatis查询方法就会自动被改造为分页查询。它帮你处理了所有底层细节重写SQL、查询总数、封装结果。而PageInfo则是PageHelper查询结果的“豪华包装器”它不仅包含了当前页的数据列表还附赠了总页数、总记录数、是否是第一页/最后一页、前后页码等一大堆你在前端分页组件里急需的信息。简单来说PageHelper让你从“手工计算分页参数并执行两条SQL”的原始时代一步跨入“声明式分页”的自动化时代。它特别适合快速开发的场景无论是管理后台、数据报表还是API接口都能让你用最少的代码实现最标准、最健壮的分页功能。接下来我会结合自己多年的使用和踩坑经验带你彻底吃透这个工具。2. 核心原理与设计思路拆解它到底是怎么“拦截”SQL的要用好一个工具最好先理解它背后的工作原理。PageHelper的魔力源于MyBatis提供的插件Interceptor机制。我们可以把MyBatis执行SQL的过程想象成一条流水线解析Mapper接口 - 获取SQL语句 - 设置参数 - 执行SQL - 处理结果。插件就像在这条流水线上安装的“智能关卡”可以在特定环节对流程进行干预。2.1 MyBatis插件机制与拦截点PageHelper实现了一个Interceptor接口并指定它拦截Executor类的query方法。Executor是MyBatis的核心执行器所有数据库查询操作最终都由它来完成。当你的代码调用Mapper.selectList()时调用链会经过这个被插件增强的Executor。插件的核心方法是intercept。PageHelper在这里面做了以下几件关键事判断是否需要分页检查当前线程上下文中是否存在分页参数即你是否调用了PageHelper.startPage。如果没有直接放行执行原始查询。获取原始SQL并改造如果需要分页它会从MappedStatement中拿到你写在XML或注解里的原始SQL。然后根据数据库方言Dialect将原始SQL改造成分页查询SQL。例如对于MySQL它会把SELECT * FROM user在运行时动态转换为SELECT * FROM user LIMIT 0, 10并同时生成一条计算总数的SQLSELECT COUNT(0) FROM user。执行改造后的SQL它先执行计算总数的SQL得到总记录数total。然后再执行加入了LIMIT的分页查询SQL得到当前页的数据列表list。封装结果最后它将list和total封装到一个Page对象中并返回。这个Page对象本身也实现了List接口所以你的业务代码感知不到变化依然按List来接收但实际上它已经“内涵”了分页信息。2.2 基于ThreadLocal的上下文传递这里有一个精妙的设计分页参数页码、页大小是如何从你调用PageHelper.startPage()的地方传递到插件内部的呢答案是ThreadLocal。ThreadLocal可以理解为每个线程独有的一个变量储物柜。当你调用PageHelper.startPage(1, 10)时它会把页码1和页大小10存入当前线程的ThreadLocal储物柜中。随后当这个线程执行MyBatis查询时PageHelper插件再从同一个ThreadLocal储物柜里把参数取出来使用。用完后插件会自动清理这个储物柜确保分页参数不会污染下一次查询。重要心得理解ThreadLocal机制是避免分页失效或混乱的关键。这意味着分页参数是线程绑定的且一次有效。如果你在调用startPage后没有立即执行查询或者在一个线程里多次查询却只想分页一次就需要格外小心。2.3 为什么选择PageHelper方案对比除了PageHelper分页还有几种常见方案手写SQL如前所述繁琐、易错、难维护。MyBatis-Plus分页MyBatis-Plus是MyBatis的增强工具其分页功能同样强大。它与PageHelper的主要区别在于集成方式。MP的分页需要配置一个PaginationInterceptor插件并且在Service层使用其提供的Page对象和selectPage方法与MP的Wrapper查询条件结合更紧密。如果你整个项目都用MP那用它的分页是更一致的选择。Spring Data JPA分页如果你是JPA技术栈那么Pageable和Page对象是标准方案与Repository集成度极高。PageHelper的优势在于对原生MyBatis的无侵入和极简使用。你不需要改变现有的MyBatis Mapper和Service的写法只需在查询前加一行代码。这对于改造遗留项目或者在不想引入MP等全套增强功能的项目中显得非常轻量和友好。3. 环境配置与集成详解从引入到生效的每一步理论懂了我们动手把它集成到项目里。这里以最主流的Spring Boot项目为例演示完整的集成过程。3.1 依赖引入首先在项目的pom.xml中添加依赖。请注意版本兼容性建议使用较新的稳定版。dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.6/version !-- 请检查最新版本 -- /dependency使用pagehelper-spring-boot-starter是最省事的方式。这个Starter会自动完成插件的配置和Bean的注册你不需要再手动写任何XML配置。如果你用的是非Spring Boot的SSM项目则需要引入pagehelper依赖并在mybatis-config.xml中手动配置插件。3.2 基础配置application.yml虽然Starter提供了自动配置但为了满足不同需求我们通常需要在application.yml中进行一些定制。下面是一个常用配置示例pagehelper: helper-dialect: mysql # 指定数据库方言这是最重要的配置 reasonable: true # 启用“合理化”参数。当pageNum0时查询第一页当pageNum总页数时查询最后一页。 support-methods-arguments: true # 支持通过Mapper接口参数来传递分页参数 params: countcountSql # 用于配置count查询的SQL映射 page-size-zero: true # 当pageSize0时返回所有结果相当于没分页配置项深度解析helper-dialect: 必须正确配置。它告诉PageHelper你的数据库类型以便生成正确的分页SQLMySQL用LIMITOracle用ROWNUM等。如果配置错误会导致生成的SQL语法错误。reasonable: 我个人强烈建议开启。这是一个非常贴心的功能。假设总共有5页用户输入了页码-1或100开启后会自动修正为第1页或第5页而不是返回空数据或抛出异常对用户体验和系统健壮性都有好处。support-methods-arguments: 这个配置允许你像这样使用分页PageUser selectByCondition(Param(“condition”) Condition cond, Param(“pageNum”) int pageNum, Param(“pageSize”) int pageSize)然后在XML中可以通过#{pageNum}和#{pageSize}获取参数。这是一种更“显式”的分页方式但不如startPage常用。3.3 验证配置是否生效配置完成后如何验证插件已经正确工作了呢一个简单的方法是查看启动日志或者写一个简单的测试。更直接的方法是开启MyBatis的SQL日志打印观察执行的SQL语句是否被改写。在application.yml中配置logging: level: com.yourmapper.package: debug # 将你的Mapper包路径设为DEBUG级别执行一个分页查询你会在日志中看到两条SQLDEBUG - Preparing: SELECT count(0) FROM user WHERE age ? DEBUG - Parameters: 18(Integer) DEBUG - Preparing: SELECT * FROM user WHERE age ? LIMIT ?, ? DEBUG - Parameters: 18(Integer), 0(Integer), 10(Integer)看到COUNT语句和带LIMIT的语句就证明PageHelper已经成功拦截并改造了SQL。4. 核心使用方式与PageInfo详解配置妥当我们来看看怎么用。PageHelper的使用核心就一句话但围绕这句话的细节和其产出的PageInfo对象才是体现功力的地方。4.1 基础用法PageHelper.startPage这是最经典、最常用的方式。在Service层或任何执行MyBatis查询的地方在查询方法之前调用。Service public class UserServiceImpl implements UserService { Autowired private UserMapper userMapper; Override public PageInfoUser getUsersByPage(int pageNum, int pageSize) { // 关键代码在此行之后第一次执行的MyBatis查询会自动分页 PageHelper.startPage(pageNum, pageSize); // 执行查询。这个List已经不是普通的ArrayList而是PageHelper内置的Page对象 ListUser userList userMapper.selectAllUsers(); // 将查询结果用PageInfo包装PageInfo包含了非常全面的分页信息 PageInfoUser pageInfo new PageInfo(userList); return pageInfo; } }必须注意的执行顺序PageHelper.startPage(pageNum, pageSize)必须紧挨着MyBatis查询语句之前调用。它们之间不能有其它数据库查询操作否则分页参数可能会被意外的查询消耗掉导致你的目标查询不分页或者为其它查询错误地加上分页。4.2 PageInfo分页信息的“瑞士军刀”直接返回ListUser给前端前端还得自己算总页数、是否有下一页太麻烦了。PageInfo就是用来解决这个问题的。它把分页的所有相关信息都打包好了。我们来看看PageInfo对象里有哪些宝贝以下属性在创建PageInfo后可直接获取// 创建PageInfo PageInfoUser pageInfo new PageInfo(userList); // 核心属性 pageInfo.getList(); // 当前页的数据列表就是传入的userList pageInfo.getTotal(); // 总记录数非常重要用于计算总页数 pageInfo.getPageNum(); // 当前页码 pageInfo.getPageSize(); // 每页显示条数 pageInfo.getPages(); // 总页数由total和pageSize计算得出 pageInfo.isIsFirstPage(); // 是否是第一页 pageInfo.isIsLastPage(); // 是否是最后一页 pageInfo.hasPreviousPage(); // 是否有上一页 pageInfo.hasNextPage(); // 是否有下一页 // 导航页码相关非常适用于生成前端页码栏 pageInfo.getNavigatePages(); // 导航栏显示的页码数量可配置默认8 pageInfo.getNavigatepageNums(); // 所有导航页的页码数组如[1,2,3,4,5] pageInfo.getPrePage(); // 上一页的页码 pageInfo.getNextPage(); // 下一页的页码前端对接示例在前后端分离项目中你可以直接将PageInfo对象序列化成JSON返回给前端。前端拿到后list用于渲染表格pageNum,pageSize,total,pages等属性直接用于配置分页组件如Element UI的Pagination几乎无需额外计算。4.3 高级用法与链式调用PageHelper也支持更灵活的链式调用可以在startPage的同时设置更多参数。// 链式调用设置页码、页大小并开启count查询默认就是开启的 PageHelper.startPage(pageNum, pageSize).count(true); // 更复杂的场景如果你只想分页但不想执行耗时的count查询比如在数据量极大时count非常慢 PageHelper.startPage(pageNum, pageSize, false); // 第三个参数设为false不进行count查询 ListUser userList userMapper.selectAllUsers(); // 此时如果你还用 new PageInfo(userList)里面的getTotal()是错的因为它拿不到总数。 // 这种情况下通常直接返回List和“是否有下一页”的标识。可以通过判断返回的list.size()是否等于pageSize来推测。什么情况下关闭count查询在无限滚动上拉加载更多的场景下前端通常不需要知道数据总量只需要判断“是否还有下一页”。此时可以先请求pageSize1条数据如果返回的数据量大于pageSize则说明还有下一页当前页只展示pageSize条并隐藏多余的那一条作为探测。这样可以避免大数据量表下COUNT(*)的性能瓶颈。5. 复杂场景下的实战与避坑指南在实际项目中分页很少是简单的SELECT *。更多是伴随着多表关联、复杂条件筛选和排序。PageHelper在这些场景下表现如何又有哪些坑需要注意5.1 多表关联查询与性能陷阱这是PageHelper最容易出问题的地方。假设我们有一个用户(user)表和订单(order)表要分页查询用户及其订单列表。错误示范导致分页结果不准!-- UserMapper.xml -- select idselectUserWithOrders resultMapuserWithOrdersMap SELECT u.*, o.order_id, o.amount FROM user u LEFT JOIN order o ON u.id o.user_id WHERE u.status 1 ORDER BY u.create_time DESC /select问题在于如果一个用户有3个订单JOIN查询后这个用户会在结果集中出现3次。PageHelper的COUNT查询是基于这个完整的JOIN后的结果集进行的。假设一页10条可能第1页只显示了4个用户因为他们总共有10个订单但COUNT查询的总数却是“订单行数”而不是“用户数”。这会导致总页数计算错误分页逻辑混乱。解决方案子查询分页推荐先分页查询出主表用户的ID再用这些ID去关联查询从表订单。select idselectUserWithOrders resultMapuserWithOrdersMap SELECT u.*, o.order_id, o.amount FROM user u LEFT JOIN order o ON u.id o.user_id WHERE u.id IN ( !-- 先分页查出用户ID -- SELECT id FROM user WHERE status 1 ORDER BY create_time DESC LIMIT #{offset}, #{pageSize} ) ORDER BY u.create_time DESC /select这种方式需要你手动计算offset失去了PageHelper的自动分页便利但逻辑最清晰性能也更好特别是user表有索引时。使用PageHelper的count查询优化PageHelper允许你为复杂的count查询单独指定一个更简单的SQL。这需要较复杂的配置且对SQL编写要求高不推荐新手使用。核心避坑点PageHelper的分页逻辑是物理分页在数据库层面用LIMIT截取数据。对于多对一如查询文章和作者的关联它工作良好。但对于一对多如查询用户和订单的关联直接在JOIN的SQL上使用PageHelper分页的主体对象用户数量会不准。务必先确定分页的“主体”并围绕主体设计查询。5.2 排序Order By与分页的配合排序是分页查询的好搭档但需要注意顺序。PageHelper.startPage(pageNum, pageSize); // 排序必须在startPage之后且格式有要求 PageHelper.orderBy(create_time DESC, id ASC); ListUser list userMapper.selectByExample(example);PageHelper.orderBy()方法接收的字符串就是SQL中ORDER BY后面的部分。特别注意PageHelper.orderBy()设置的是最终执行SQL的排序它可能会与你XML中写的ORDER BY子句冲突或叠加造成混乱。更清晰、更推荐的做法是将排序逻辑直接写在XML的SQL语句中。5.3 与MyBatis动态SQL如if标签的协作PageHelper与MyBatis的动态SQL协作是天衣无缝的。因为插件是在MyBatis构建完最终的SQL语句之后才进行拦截和改写的。所以无论你的XML里用了多少if、choose标签来动态拼接条件PageHelper都能正确地对最终生成的SQL进行分页处理完全不用担心。5.4 在事务方法中的使用这是一个非常隐蔽的坑。考虑以下代码Transactional public void someBusinessMethod() { // 业务逻辑A... PageHelper.startPage(1, 10); ListUser list1 userMapper.selectA(); // 查询1 // ... 更多业务逻辑 ListOrder list2 orderMapper.selectB(); // 查询2 }在同一个事务方法中如果你在查询1后没有清空分页参数那么查询2也会被分页因为PageHelper使用ThreadLocal存储参数而Spring的事务管理通常会让同一个线程执行整个Transactional方法。解决方法PageHelper提供了一个安全清除线程上下文的方法。在每次分页查询后如果后续还有不希望分页的查询应该手动清理。PageHelper.startPage(1, 10); ListUser list1 userMapper.selectA(); // 清理分页参数防止影响后续查询 PageHelper.clearPage(); ListOrder list2 orderMapper.selectB(); // 这次不会被分页了养成好习惯在确定只需要一次分页的场景下查询完成后立即调用PageHelper.clearPage()。6. 常见问题排查与性能优化技巧即使理解了原理实战中还是会遇到各种奇怪的问题。这里我整理了一份“急救手册”。6.1 问题排查速查表问题现象可能原因解决方案分页完全不生效1.PageHelper.startPage()在查询之后调用。2.PageHelper.startPage()与查询语句之间有其他数据库查询。3. 依赖或配置错误插件未成功加载。1. 确保startPage紧邻目标查询之前。2. 检查中间是否有其他Mapper调用。3. 检查日志确认PageHelper插件已加载检查helper-dialect配置。分页结果混乱总数不对1. SQL是多表JOIN且为一对多关系见5.1节。2. SQL中包含GROUP BYCOUNT查询结果不是期望的行数。1. 重构SQL使用子查询先分页主体。2. 考虑关闭本次查询的count或重写count查询。抛出SQL语法错误helper-dialect配置错误生成了不适用于当前数据库的SQL。检查并修正application.yml中的pagehelper.helper-dialect配置。线程安全问题A请求的分页参数影响了B请求分页参数未及时清理且请求处理使用了线程池如Tomcat线程池线程被复用。1. 确保每次分页查询后在finally块中调用PageHelper.clearPage()。2. 使用PageHelper的Page对象它实现了Closeable配合try-with-resources语法自动清理。COUNT查询非常慢表数据量巨大且查询条件复杂没有合适的索引。1. 为WHERE条件和ORDER BY字段添加索引。2. 如非必要关闭count查询startPage(pageNum, pageSize, false)。3. 考虑使用估算行数或缓存总条数。6.2 性能优化建议索引是王道分页查询的性能瓶颈往往在ORDER BY和WHERE条件上而不是LIMIT本身。确保排序字段和常用查询条件字段上有合适的索引。对于ORDER BY create_time DESC LIMIT N这类查询对create_time建立索引是必须的。避免大偏移量OffsetLIMIT 1000000, 20这种查询MySQL需要先扫描前100万条记录然后扔掉它们再取20条效率极低。对于深度分页业务上限制不允许跳转到太靠后的页或者用“下一页”代替精确页码。使用“游标”或“seek方法”记录上一页最后一条记录的ID或排序字段值下一页查询用WHERE id last_id LIMIT 20。这需要业务逻辑配合且排序字段必须唯一。审慎使用count(1)PageHelper默认使用count(0)或count(1)。在MySQL中count(*)经过优化通常是最快的。你可以通过pagehelper.count-sql配置项自定义COUNT查询例如设置为count(*)。监控与日志在生产环境关注慢SQL日志。如果发现分页查询慢要具体分析是COUNT慢还是主查询慢然后对症下药。6.3 关于MyBatis-Plus分页的补充对比很多同学会纠结用PageHelper还是MyBatis-Plus的分页。这里再清晰对比一下PageHelper优势是简单、直接、无侵入。适合原生MyBatis项目或只需要分页这一项增强功能的场景。它的“魔法”来自于线程上下文拦截理解其原理对避坑很重要。MyBatis-Plus分页优势是功能整合、风格统一。MP的分页是其整个CRUD增强体系的一部分与它的QueryWrapper、UpdateWrapper等条件构造器配合使用非常流畅。如果你已经在使用MP的BaseMapper、Service等全套功能那么继续使用它的分页是更自然的选择。MP的分页配置也是一个Interceptor但使用方式是在Service层传入一个Page对象。选择哪一个取决于你的项目技术栈和团队习惯。对于新项目如果确定会用到MP的多种增强功能直接上MP是更全面的选择。如果只是老项目加个分页或者想保持框架的轻量PageHelper是绝佳的利器。最后再强调一个我踩过多次的坑永远记得PageHelper.startPage()只对其后第一个MyBatis查询生效并且要注意在事务方法或线程复用场景下及时清理。把这个原则刻在脑子里能解决90%的奇怪问题。工具虽好理解了它的脾气才能用得顺手。