刚接手一个老项目时我面临过一个挺现实的抉择数据访问层已经从原生 MyBatis 全部迁移到了 MyBatis Plus但分页这块团队上下用的还是 Pagehelper而且线上跑了两年一直很稳。当时我的第一反应和大多数人一样——既然都用 MyBatis Plus 了分页为什么不直接用它的自带插件结果真去改的时候才发现事情没那么简单。这个内容就是讲清楚一件事在 MyBatis Plus 项目里Pagehelper 到底是怎么作为一套“扩展方法”继续发挥作用的为什么在不少场景下它甚至比 MP 自带分页更好用以及集成过程中那些文档里不会写明白的坑。无论你是刚接触这两个技术栈的初学者还是打算在现有项目里平滑引入 Pagehelper 的老手这篇文章都会有点用。1. 两个分页插件我为什么最终留下了 Pagehelper很多从 Spring Boot MyBatis 一路走过来的开发者对 Pagehelper 都有感情。它属于那种“用起来没感觉、没它又不行”的基础设施。而 MyBatis Plus 自带的PaginationInnerInterceptor也相当成熟两者都能实现物理分页但设计哲学差别很大。1.1 MyBatis Plus 自带分页插件其实不差MyBatis Plus 在 3.x 版本后主推MybatisPlusInterceptor 各种 InnerInterceptor 的组合方式其中PaginationInnerInterceptor负责分页。用法很简单Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }配置完之后Mapper 层只要继承了BaseMapper就能直接用selectPage方法拿到IPage结果PageUserVO page new Page(pageNum, pageSize); IPageUserVO result userMapper.selectPage(page, wrapper);这套方案的好处很明显连贯、面向对象、且基于 MyBatis Plus 的体系收紧。分页参数是作为一个对象传给 SQL 的不走线程变量天然就避免了“分页串页”这种经典问题。1.2 但老项目里 Pagehelper 的人情债很难还清既然 MP 自带分页不差为什么我还要在项目里继续用 Pagehelper核心原因有三个。第一存量 SQL 的兼容性。老项目里大量自定义 XML 查询很多 SQL 是当年针对复杂报表写的拼接条件、子查询、临时表用得飞起。这些 Mapper 方法并不都继承BaseMapper有些是纯自定义方法。MP 自带分页插件对自定义方法的支持虽然已经不错但遇到特别离谱的 SQL还是需要额外配置和测试。而 Pagehelper 因为是从 MyBatis 时代就一直在用的对“任意 SQL 都能分页”这件事的兜底能力非常强。第二自动 count 查询与参数合理化。PageHelper.startPage(pageNum, pageSize)调用后Pagehelper 会自动生成 count 查询并且每次翻页前会自动修正非法的页码参数。比如 pageSize 传了 1000reasonable: true配置下会被压回配置上限pageNum 传了 -1 或超过总页数会自动归位到第一页或最后一页。这个“参数兜底”机制在内部系统里特别省心。第三团队惯性。说实话这可能是最现实的一条。团队里写了三五年 MyBatis 的同事早就习惯了PageHelper.startPage()这种命令式的写法让他们换 MP 的Page对象不是不能换而是没有必要为了“统一技术栈”去承担回归测试的成本。我把两套方案的核心差异梳理成了表格方便你凭实际场景做取舍对比维度MyBatis Plus 自带分页Pagehelper分页参数传递Page 对象作为方法参数ThreadLocal startPage命令对自定义 SQL 的兼容较好但复杂 SQL 需测试极强拦截器层面兜底自动 count 优化需手动配置 count 方法自动生成支持自定义 count非法参数处理需业务层自行判断reasonable自动修正与 MP 体系耦合度强天然一体化弱属于“独立扩展”依赖侵入无额外依赖需引入 pagehelper 依赖所以我的结论是如果你是从零开始的新项目直接用 MP 自带分页没毛病但如果你维护的是一个已经成型的中大型项目Pagehelper 作为扩展方法接入 MyBatis Plus是一种成本更低、风险更小的方案。2. Pagehelper 在 MyBatis Plus 工程里的接入原理要在一个基于 MyBatis Plus 的项目里顺畅使用 Pagehelper光会startPage是不够的你至少得知道它底层做了什么否则遇到诡异问题会无从下手。2.1 从一条 select 的拦截说起Pagehelper 的本质是一个 MyBatis 拦截器Interceptor它拦截的是Executor接口的query方法。我先不展开源代码你用大白话理解就是当 Mapper 里的某个查询被触发时Pagehelper 在真正执行 SQL 之前先“截胡”了一下看看当前线程有没有分页需求。有分页需求的标准做法是调用PageHelper.startPage(pageNum, pageSize)。这个方法内部会把分页参数保存到一个名为Page的 ThreadLocal 变量里。紧接着执行的第一次查询Pagehelper 就会从 ThreadLocal 取出分页参数拦截到原始 SQL利用方言Dialect生成带LIMIT的物理分页 SQL根据需要生成 count 查询查询总记录数执行分页 SQL把数据查出来组装成PageInfo清空 ThreadLocal避免参数污染下一次查询。整个流程听上去很复杂但对使用者来说就一句话startPage之后跟的那条查询语句会自动被带上分页条件。2.2 关键点它为什么拦得住 MyBatis Plus 的 BaseMapper 方法很多人担心MyBatis Plus 的 Mapper 方法是框架内部封装好的Pagehelper 会不会拦不到实际上不会。MyBatis Plus 底层的BaseMapper方法最终也是通过SqlSessionTemplate去调用 SqlSession 的selectList方法而selectList最终绕不开Executor。也就是说只要你的 Mapper 方法最终走了 MyBatis 的执行链路Pagehelper 的拦截器就一定能截到。我第一次在一个纯 MP 项目中测试时写完userMapper.selectList(wrapper)之后前面加上PageHelper.startPage(1, 10)结果真的分页成功了。那一刻我意识到Pagehelper 这种拦截器方案在“通用性”上确实无敌——它根本不关心你的 SQL 是手写的还是框架生成的。这也是它作为“扩展方法”存在的核心价值对 MyBatis Plus 来说Pagehelper 不是竞争者而是能力补充。2.3 拦截器顺序导致分页失效的第一个坑既然 Pagehelper 是一个 Interceptor而 MyBatis Plus 的分页插件本身也是一个 Interceptor那么两者在同一个 SqlSession 上注册时就存在顺序问题。MyBatis 的拦截器是通过InterceptorChain维护的多个拦截器叠加是一个“层层代理”的关系。执行顺序通常会按照插件配置的顺序来。如果配置不合理可能出现的情况是Pagehelper 先改写了 SQLMP 的分页插件又改了一遍导致 SQL 被重复改写或者反过来MP 先处理了查询Pagehelper 发现当前查询已经被处理过跳过分页。这里我踩过一个很实际的坑项目里原先只配置了 Pagehelper后来为了让 MP 的selectPage能用又加了PaginationInnerInterceptor。结果两个拦截器同时生效列表接口开始出现 count 查询忽多忽少、limit 被拼接两次的情况。排查过程是这样的我先在代码里断点查看两个拦截器的注册顺序然后在application.yml中设置了pagehelper.interceptor-offset不为零试图调整顺序但没有明显改善。最后干脆做了个决定在一个项目里分页功能优先用 PagehelperMP 自带的分页拦截器不注册。因为 Pagehelper 既然能拦到 MP 的所有查询那就没必要再养一个重复能力的拦截器了。到这一步原理层面就通了。3. 手把手把 Pagehelper 塞进 MyBatis Plus 项目下面进入实操环节。我会按“依赖引入 → 配置编写 → 代码封装 → 与 MP 共存”的顺序把完整落地方式捋一遍。3.1 依赖引入与版本矩阵Pagehelper 在 Spring Boot 2.x 时代最常用的是pagehelper-spring-boot-starter在 Spring Boot 3.x 时代则要换用pagehelper-spring-boot-starter的新版本或单独引入pagehelper核心包。这里给出一份我实测过可以稳定工作的版本组合技术栈推荐版本Spring Boot 2.x2.7.xMyBatis Plus3.5.xpagehelper-spring-boot-starter1.4.7Pagehelper 核心版本5.3.xstarter 传递依赖Maven 依赖示例dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.7/version /dependency如果项目是 Spring Boot 3建议把版本升到 2.x 版本线比如dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version2.1.0/version /dependency注意pagehelper-spring-boot-starter会自动适配当前 Spring Boot 版本但引入后要留意传递依赖是否把 MyBatis 的版本给改了。如果项目里同时用了 MyBatis Plus 的 starter要确认两者底层 MyBatis 版本一致否则会出现NoSuchMethodError之类的奇怪问题。我在一个 Spring Boot 3.2 的测试项目里遇到过这种冲突MP 的 starter 默认带的是 MyBatis 3.5.16pagehelper starter 传递下来的是 3.5.13最终启动时提示SqlSessionFactory创建异常。解决办法很简单在 pom.xml 里用dependencyManagement锁定 MyBatis 版本或者排除掉 pagehelper starter 中的 mybatis 依赖统一走 MP 的版本。3.2 配置文件的完整写法依赖引入后在application.yml里做如下配置pagehelper: helper-dialect: mysql reasonable: true support-methods-arguments: true params: countcountSql auto-runtime-dialect: truehelper-dialect指定数据库方言。这里写 mysqlPagehelper 会生成对应的LIMIT语句。reasonable开启参数合理化。pageNum 0 时默认返回第一页pageNum 总页数时返回最后一页。support-methods-arguments支持从方法参数中读取分页信息。举个例子如果你的 Mapper 方法有pageNum和pageSize两个参数开启这个选项后Pagehelper 会自动识别不会跟你手动startPage冲突。params配置 count 查询的默认参数名。auto-runtime-dialect允许运行时自动检测方言连接不同的数据库时比较有用。这里有个小细节如果你同时在代码里调用了PageHelper.startPage(pageNum, pageSize)又在 Mapper 方法参数中新加了Page对象Pagehelper 会以startPage为准而不是以方法参数为准。所以为了避免理解上的混乱建议一个项目里只采用一种传参方式要么纯startPage要么纯方法参数不要混合用。3.3 核心代码一个封装好的分页查询方法日常开发里我们会习惯把分页逻辑封装在 Service 层避免 Controller 直接依赖 Pagehelper 的静态方法。Service public class UserService { private final UserMapper userMapper; public UserService(UserMapper userMapper) { this.userMapper userMapper; } public PageResultUserVO pageUser(UserQuery query) { // 1. 开启分页 PageHelper.startPage(query.getPageNum(), query.getPageSize()); // 2. 执行查询这条查询会被拦截并自动加上 LIMIT ListUserVO userList userMapper.selectUserList(query); // 3. 封装 PageInfo PageInfoUserVO pageInfo new PageInfo(userList); // 4. 转成统一返回结构 return PageResult.of(pageInfo.getList(), pageInfo.getTotal()); } }Mapper 接口方法不需要任何额外处理public interface UserMapper extends BaseMapperUser { ListUserVO selectUserList(Param(query) UserQuery query); }XML 里正常写 SQL 就行不要用手动 LIMIT否则 Pagehelper 会叠加一个 LIMIT导致数据变成“只查前 N 条之后的 N 条”这种错位结果。select idselectUserList resultTypecom.example.vo.UserVO select id, username, email, status, create_time from user where if testquery.username ! null and query.username ! and username like concat(%, #{query.username}, %) /if if testquery.status ! null and status #{query.status} /if /where order by create_time desc /select这段代码别小看它就是 Pagehelper 在 MyBatis Plus 项目里工作的标准范式。startPage之后紧接着的查询会被上分页其他查询不受影响。3.4 让 Pagehelper 和 MP 的分页插件共存的处理方式如果你的项目里已经配置了 MP 的PaginationInnerInterceptor并且你不想删掉它那 Pagehelper 仍然可以共存但有几个纪律必须遵守同一个查询只能走一种分页方式。要么用PageHelper.startPageselectList要么用Page参数 selectPage绝不能在一个查询上同时触发两套分页。Pagehelper 与 MP 分页拦截器可以按需拆分使用。比如核心业务列表用 MP 的selectPage复杂报表查询用 Pagehelper 兜底。这其实是一种很实际的分工MP 负责标准 CRUD 的分页Pagehelper 负责“疑难杂症” SQL 的分页。控制拦截器的执行顺序。如果你执意要让两者共存需要自定义ConfigurationCustomizer来控制 Interceptor 的注册顺序Configuration public class MybatisConfig { Bean public ConfigurationCustomizer mybatisConfigurationCustomizer() { return configuration - { // 确保 Pagehelper 优先于其他拦截器处理 }; } }但说实话踩过几次坑后我的建议是在同一个项目中分页的功能尽量收敛为一种方案。真遇到 Pagehelper 分页不了的极端 SQL再针对性处理而不是长期维护两套分页逻辑否则团队协作时很容易互相踩脚。4. 集成之后绕不开的坑我一个个说配置写好了、代码跑通了不等于就万事大吉。我在落地过程中遇到的几个典型问题值得单独拿出来讲透。4.1 场景 ABaseMapper.selectPage与 Pagehelper 的混乱前面说过MP 的BaseMapper自带了一个selectPage方法。这个方法的设计是配合 MP 分页插件使用的它期望Page作为参数传入。如果你在同一个方法里先调用了PageHelper.startPage然后又调用了selectPage会发生什么答案是Pagehelper 会把selectPage也当成一个普通查询去拦截而 MP 的selectPage又会根据Page对象再去拼一次 LIMIT。最终结果要么是 SQL 拼接错乱要么 count 查询异常。正确处理方式是明确区分两种写法。走 Pagehelper 时用selectList或自定义 XMLPageHelper.startPage(pageNum, pageSize); ListUser users userMapper.selectList(wrapper); PageInfoUser pageInfo new PageInfo(users);走 MP 自带分页时用selectPagePageUser page new Page(pageNum, pageSize); IPageUser result userMapper.selectPage(page, wrapper);这俩千万不要混着用。你可能觉得这只是“规范”问题但线上出现过因为某次重构同事在循环里误加了startPage导致后续所有接口第一次查询都被分页的严重问题。4.2 场景 Bcount 自动优化在复杂 SQL 下的意外Pagehelper 自动生成 count 查询时逻辑比较简单它会尝试把原始 SQL 改写成select count(0) from (原始SQL) table_count的形式。对于简单查询这没问题但对于包含 group by、distinct、union、多表 join 的复杂 SQL自动 count 可能会导致性能骤降。我遇到过一条带 group by 的报表 SQL原始查询 200ms 跑完Pagehelper 自动生成的 count 查询居然跑了 1.6 秒。原因就是它把整条 SQL 套了一层子查询让 MySQL 做了全量聚合后再 count。解决方案有两个第一种针对具体查询手工指定 countPageHelper.startPage(pageNum, pageSize); PageHelper.count(() - userMapper.countUserGroup(query)); ListUserVO list userMapper.selectUserGroup(query);第二种在 XML 里自定义 count SQL并在调用时增加countSuffix参数让 Pagehelper 使用指定的 count 方法。我实际项目里更倾向第二个方案因为它能让“count 走单独的轻量 SQL”成为团队规范而不是每个开发各自想办法。4.3 场景 C分页静默失效排查链路还原分页失效是 Pagehelper 最隐蔽的问题。代码没错、配置没错但结果就是不分页或者偶尔分页偶尔不分页。我复盘了一个真实案例。某个接口分页不定时失效。排查过程大致是先确认是否在同一个线程里开启了分页。如果startPage在子线程里调用而查询在主线程执行ThreadLocal 不共享分页自然不生效。再检查调用链里有没有Async。如果 Service 方法是异步执行的ThreadLocal 上下文就断了。期间还遇到过一个很经典的问题startPage之后执行查询之前中间穿插了其他耗时的远程调用由于无法保证同一个线程执行分页参数被清空查询走成了全量。最后定位到真正的原因——循环中多次调用startPage。某个批量导出功能在一个 for 循环里分批调用了分页查询每次都调PageHelper.startPage但最后一轮查询并不是紧跟着最新一次startPage的查询而是循环里其它节点上的查询导致这一节点被错误分页真正要分页的查询却因为 ThreadLocal 被后续调用覆盖而失效。这个问题的根治方式是让startPage和查询尽可能相邻并且保持在同一作用域内。不要在调用链中间穿插无关逻辑。如果团队里经常有人踩这个坑可以考虑封装统一的 PageQueryService把“启动分页 查询 收集结果”做成模板方法减少误用空间。4.4 场景 D嵌套结果映射导致的数据错位这是高级用法里最容易出问题的地方。当查询包含一对多关系时比如查订单列表同时要带出订单项很多人会写这样的结果映射resultMap idorderWithItems typecom.example.OrderVO id propertyid columnid/ collection propertyitems ofTypecom.example.OrderItemVO ... /collection /resultMap这种 N1 转嵌套结果的 SQL在分页时会出现一个尴尬情况Pagehelper 是对主查询的每行结果进行 LIMIT但 MyBatis 的嵌套结果映射会在内存里合并一对多数据导致合并后的行数和 SQL 返回的行数对不上。表现就是一页设置 10 条结果返回了 5 个订单因为有些订单带了两三条明细或者反过来明明订单有 8 条但页面只显示 5 条因为其中几条在上翻页时被“吃”掉了。处理这类问题业界公认的靠谱方案是先分页子查询再连表补全明细或者用collection的select属性走嵌套查询。Pagehelper 不背这个锅它只负责基于 SQL 结果行数分页理解这一点就能在设计 SQL 时主动避开“先合并再分页”的错误。5. 进阶结合 MyBatis Plus DDL 把分页玩成完整闭环最近“MyBatis Plus DDL”算是热词了很多人在讨论 MyBatis Plus 3.5.3 版本提供的动态 DDL 管理能力。用大白话说就是你可以通过 Java 代码直接创建表、修改表结构而不必手工去数据库执行脚本。这个能力配合 Pagehelper 的分页查询能非常优雅地解决一类常见需求管理后台的动态表单、报表、配置中心这类“数据表不固定”的业务场景。5.1 为什么这两者会走到一起过去我们做动态表单比如用户的客户可以自定义字段最粗暴的方案是先设计一张 EAV 表Entity-Attribute-Value一行一个属性。这种方式实现简单但查询性能很差字段多了以后 SQL 写起来想骂人。另一种方案是动态建表用户每创建一个新表单系统在后台CREATE TABLE一张物理表列结构由用户定义。这种方式查询性能好、符合业务直觉但需要付出表结构管理的成本。MyBatis Plus DDL 就补上这一环。表建好了下一步自然是列表展示默认要分页、搜索、排序。这时候 Pagehelper 的价值就体现出来了因为它不关心表名和列名是硬编码的还是运行时拼接的只要 SQL 在它就能分页。5.2 一个动态报表列表的完整实现假设现在要做一个“动态表单数据浏览”功能用户通过配置创建了一个名为form_customer_2025的表结构如下CREATE TABLE form_customer_2025 ( id bigint(20) NOT NULL AUTO_INCREMENT, customer_name varchar(100) DEFAULT NULL, phone varchar(20) DEFAULT NULL, created_at datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;在 MyBatis Plus 中可以使用 DDL 功能在代码里创建这张表这里不做过多展开核心思路是使用DDL相关 API 执行建表 SQL。建好之后分页查询就是典型的动态 SQL 场景表名、列名来自配置不能写死在 XML 里。这时可以用Select注解拼 SQL或者干脆构造一个动态SqlSource。我这里给一个用 MyBatis 注解方式的简单示例public interface DynamicFormMapper { Select(select * from ${tableName} where ${condition} order by id desc) ListMapString, Object queryFormData(Param(tableName) String tableName, Param(condition) String condition); }Service 层使用 Pagehelper 分页public PageResultMapString, Object pageFormData(String tableName, String condition, Integer pageNum, Integer pageSize) { PageHelper.startPage(pageNum, pageSize); ListMapString, Object dataList dynamicFormMapper.queryFormData(tableName, condition); PageInfoMapString, Object pageInfo new PageInfo(dataList); return PageResult.of(pageInfo.getList(), pageInfo.getTotal()); }这里有一个实操中很容易踩的雷动态表名拼接会导致 Pagehelper 生成的 count SQL 也要能正确解析表名。如果 condition 里有引号、特殊字符或者表名带了库名前缀count 查询可能因为 SQL 语法问题失败。我的建议是动态表名的场景下尽量保持 condition 简单或者单独配置countSql参数让 count 走一套更保险的 SQL。5.3 Pagehelper 对动态 SQL 场景的适配建议在动态 SQL 场景下使用 Pagehelper我总结了几条经验入参统一用 Map避免因为参数类型变化导致support-methods-arguments识别不到分页参数。尽量保证动态查询中order by是稳定存在的分页查询如果不排序翻页时数据会抖动用户看着像是在重复或丢数据。count 查询建议单独提供因为动态 SQL 的稳定性本来就差自动 count 再套一层子查询会放大风险。这个场景其实就是“MyBatis Plus 扩展方法”这个标题最好的落地诠释以 MP 作为数据访问的基础框架以 DDL 能力支撑动态表结构以 Pagehelper 补充分页查询的短板三者配合能覆盖很多常规 CRUD 框架搞不定的业务形态。写在最后的一点个人体会在实际项目里折腾完这一圈我最深的感受是技术选型永远没有“绝对正确”只有“当前阶段合适”。MyBatis Plus 自带分页对于规整的 CRUD 业务非常顺滑但 Pagehelper 这种老牌插件的生存能力强在“兜底能力”——不管业务 SQL 长什么样它都能按照预期去分页。这种兜底能力在复杂系统里的价值远比“少写一行代码”重要得多。如果你现在正准备在 MyBatis Plus 项目里接入 Pagehelper记住三件事一是依赖和版本尽量统一避免 MyBatis 版本冲突二是startPage和查询尽量写在一起中间不要插无关逻辑三是不要把两套分页搅在一起用定好规范团队少流汗。踩坑不可怕可怕的是坑就在那没人把它写在文档里。希望这篇内容能让你在走这条路时少翻几次车。
刚接手一个老项目时我面临过一个挺现实的抉择数据访问层已经从原生 MyBatis 全部迁移到了 MyBatis Plus但分页这块团队上下用的还是 Pagehelper而且线上跑了两年一直很稳。当时我的第一反应和大多数人一样——既然都用 MyBatis Plus 了分页为什么不直接用它的自带插件结果真去改的时候才发现事情没那么简单。这个内容就是讲清楚一件事在 MyBatis Plus 项目里Pagehelper 到底是怎么作为一套“扩展方法”继续发挥作用的为什么在不少场景下它甚至比 MP 自带分页更好用以及集成过程中那些文档里不会写明白的坑。无论你是刚接触这两个技术栈的初学者还是打算在现有项目里平滑引入 Pagehelper 的老手这篇文章都会有点用。1. 两个分页插件我为什么最终留下了 Pagehelper很多从 Spring Boot MyBatis 一路走过来的开发者对 Pagehelper 都有感情。它属于那种“用起来没感觉、没它又不行”的基础设施。而 MyBatis Plus 自带的PaginationInnerInterceptor也相当成熟两者都能实现物理分页但设计哲学差别很大。1.1 MyBatis Plus 自带分页插件其实不差MyBatis Plus 在 3.x 版本后主推MybatisPlusInterceptor 各种 InnerInterceptor 的组合方式其中PaginationInnerInterceptor负责分页。用法很简单Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }配置完之后Mapper 层只要继承了BaseMapper就能直接用selectPage方法拿到IPage结果PageUserVO page new Page(pageNum, pageSize); IPageUserVO result userMapper.selectPage(page, wrapper);这套方案的好处很明显连贯、面向对象、且基于 MyBatis Plus 的体系收紧。分页参数是作为一个对象传给 SQL 的不走线程变量天然就避免了“分页串页”这种经典问题。1.2 但老项目里 Pagehelper 的人情债很难还清既然 MP 自带分页不差为什么我还要在项目里继续用 Pagehelper核心原因有三个。第一存量 SQL 的兼容性。老项目里大量自定义 XML 查询很多 SQL 是当年针对复杂报表写的拼接条件、子查询、临时表用得飞起。这些 Mapper 方法并不都继承BaseMapper有些是纯自定义方法。MP 自带分页插件对自定义方法的支持虽然已经不错但遇到特别离谱的 SQL还是需要额外配置和测试。而 Pagehelper 因为是从 MyBatis 时代就一直在用的对“任意 SQL 都能分页”这件事的兜底能力非常强。第二自动 count 查询与参数合理化。PageHelper.startPage(pageNum, pageSize)调用后Pagehelper 会自动生成 count 查询并且每次翻页前会自动修正非法的页码参数。比如 pageSize 传了 1000reasonable: true配置下会被压回配置上限pageNum 传了 -1 或超过总页数会自动归位到第一页或最后一页。这个“参数兜底”机制在内部系统里特别省心。第三团队惯性。说实话这可能是最现实的一条。团队里写了三五年 MyBatis 的同事早就习惯了PageHelper.startPage()这种命令式的写法让他们换 MP 的Page对象不是不能换而是没有必要为了“统一技术栈”去承担回归测试的成本。我把两套方案的核心差异梳理成了表格方便你凭实际场景做取舍对比维度MyBatis Plus 自带分页Pagehelper分页参数传递Page 对象作为方法参数ThreadLocal startPage命令对自定义 SQL 的兼容较好但复杂 SQL 需测试极强拦截器层面兜底自动 count 优化需手动配置 count 方法自动生成支持自定义 count非法参数处理需业务层自行判断reasonable自动修正与 MP 体系耦合度强天然一体化弱属于“独立扩展”依赖侵入无额外依赖需引入 pagehelper 依赖所以我的结论是如果你是从零开始的新项目直接用 MP 自带分页没毛病但如果你维护的是一个已经成型的中大型项目Pagehelper 作为扩展方法接入 MyBatis Plus是一种成本更低、风险更小的方案。2. Pagehelper 在 MyBatis Plus 工程里的接入原理要在一个基于 MyBatis Plus 的项目里顺畅使用 Pagehelper光会startPage是不够的你至少得知道它底层做了什么否则遇到诡异问题会无从下手。2.1 从一条 select 的拦截说起Pagehelper 的本质是一个 MyBatis 拦截器Interceptor它拦截的是Executor接口的query方法。我先不展开源代码你用大白话理解就是当 Mapper 里的某个查询被触发时Pagehelper 在真正执行 SQL 之前先“截胡”了一下看看当前线程有没有分页需求。有分页需求的标准做法是调用PageHelper.startPage(pageNum, pageSize)。这个方法内部会把分页参数保存到一个名为Page的 ThreadLocal 变量里。紧接着执行的第一次查询Pagehelper 就会从 ThreadLocal 取出分页参数拦截到原始 SQL利用方言Dialect生成带LIMIT的物理分页 SQL根据需要生成 count 查询查询总记录数执行分页 SQL把数据查出来组装成PageInfo清空 ThreadLocal避免参数污染下一次查询。整个流程听上去很复杂但对使用者来说就一句话startPage之后跟的那条查询语句会自动被带上分页条件。2.2 关键点它为什么拦得住 MyBatis Plus 的 BaseMapper 方法很多人担心MyBatis Plus 的 Mapper 方法是框架内部封装好的Pagehelper 会不会拦不到实际上不会。MyBatis Plus 底层的BaseMapper方法最终也是通过SqlSessionTemplate去调用 SqlSession 的selectList方法而selectList最终绕不开Executor。也就是说只要你的 Mapper 方法最终走了 MyBatis 的执行链路Pagehelper 的拦截器就一定能截到。我第一次在一个纯 MP 项目中测试时写完userMapper.selectList(wrapper)之后前面加上PageHelper.startPage(1, 10)结果真的分页成功了。那一刻我意识到Pagehelper 这种拦截器方案在“通用性”上确实无敌——它根本不关心你的 SQL 是手写的还是框架生成的。这也是它作为“扩展方法”存在的核心价值对 MyBatis Plus 来说Pagehelper 不是竞争者而是能力补充。2.3 拦截器顺序导致分页失效的第一个坑既然 Pagehelper 是一个 Interceptor而 MyBatis Plus 的分页插件本身也是一个 Interceptor那么两者在同一个 SqlSession 上注册时就存在顺序问题。MyBatis 的拦截器是通过InterceptorChain维护的多个拦截器叠加是一个“层层代理”的关系。执行顺序通常会按照插件配置的顺序来。如果配置不合理可能出现的情况是Pagehelper 先改写了 SQLMP 的分页插件又改了一遍导致 SQL 被重复改写或者反过来MP 先处理了查询Pagehelper 发现当前查询已经被处理过跳过分页。这里我踩过一个很实际的坑项目里原先只配置了 Pagehelper后来为了让 MP 的selectPage能用又加了PaginationInnerInterceptor。结果两个拦截器同时生效列表接口开始出现 count 查询忽多忽少、limit 被拼接两次的情况。排查过程是这样的我先在代码里断点查看两个拦截器的注册顺序然后在application.yml中设置了pagehelper.interceptor-offset不为零试图调整顺序但没有明显改善。最后干脆做了个决定在一个项目里分页功能优先用 PagehelperMP 自带的分页拦截器不注册。因为 Pagehelper 既然能拦到 MP 的所有查询那就没必要再养一个重复能力的拦截器了。到这一步原理层面就通了。3. 手把手把 Pagehelper 塞进 MyBatis Plus 项目下面进入实操环节。我会按“依赖引入 → 配置编写 → 代码封装 → 与 MP 共存”的顺序把完整落地方式捋一遍。3.1 依赖引入与版本矩阵Pagehelper 在 Spring Boot 2.x 时代最常用的是pagehelper-spring-boot-starter在 Spring Boot 3.x 时代则要换用pagehelper-spring-boot-starter的新版本或单独引入pagehelper核心包。这里给出一份我实测过可以稳定工作的版本组合技术栈推荐版本Spring Boot 2.x2.7.xMyBatis Plus3.5.xpagehelper-spring-boot-starter1.4.7Pagehelper 核心版本5.3.xstarter 传递依赖Maven 依赖示例dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.7/version /dependency如果项目是 Spring Boot 3建议把版本升到 2.x 版本线比如dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version2.1.0/version /dependency注意pagehelper-spring-boot-starter会自动适配当前 Spring Boot 版本但引入后要留意传递依赖是否把 MyBatis 的版本给改了。如果项目里同时用了 MyBatis Plus 的 starter要确认两者底层 MyBatis 版本一致否则会出现NoSuchMethodError之类的奇怪问题。我在一个 Spring Boot 3.2 的测试项目里遇到过这种冲突MP 的 starter 默认带的是 MyBatis 3.5.16pagehelper starter 传递下来的是 3.5.13最终启动时提示SqlSessionFactory创建异常。解决办法很简单在 pom.xml 里用dependencyManagement锁定 MyBatis 版本或者排除掉 pagehelper starter 中的 mybatis 依赖统一走 MP 的版本。3.2 配置文件的完整写法依赖引入后在application.yml里做如下配置pagehelper: helper-dialect: mysql reasonable: true support-methods-arguments: true params: countcountSql auto-runtime-dialect: truehelper-dialect指定数据库方言。这里写 mysqlPagehelper 会生成对应的LIMIT语句。reasonable开启参数合理化。pageNum 0 时默认返回第一页pageNum 总页数时返回最后一页。support-methods-arguments支持从方法参数中读取分页信息。举个例子如果你的 Mapper 方法有pageNum和pageSize两个参数开启这个选项后Pagehelper 会自动识别不会跟你手动startPage冲突。params配置 count 查询的默认参数名。auto-runtime-dialect允许运行时自动检测方言连接不同的数据库时比较有用。这里有个小细节如果你同时在代码里调用了PageHelper.startPage(pageNum, pageSize)又在 Mapper 方法参数中新加了Page对象Pagehelper 会以startPage为准而不是以方法参数为准。所以为了避免理解上的混乱建议一个项目里只采用一种传参方式要么纯startPage要么纯方法参数不要混合用。3.3 核心代码一个封装好的分页查询方法日常开发里我们会习惯把分页逻辑封装在 Service 层避免 Controller 直接依赖 Pagehelper 的静态方法。Service public class UserService { private final UserMapper userMapper; public UserService(UserMapper userMapper) { this.userMapper userMapper; } public PageResultUserVO pageUser(UserQuery query) { // 1. 开启分页 PageHelper.startPage(query.getPageNum(), query.getPageSize()); // 2. 执行查询这条查询会被拦截并自动加上 LIMIT ListUserVO userList userMapper.selectUserList(query); // 3. 封装 PageInfo PageInfoUserVO pageInfo new PageInfo(userList); // 4. 转成统一返回结构 return PageResult.of(pageInfo.getList(), pageInfo.getTotal()); } }Mapper 接口方法不需要任何额外处理public interface UserMapper extends BaseMapperUser { ListUserVO selectUserList(Param(query) UserQuery query); }XML 里正常写 SQL 就行不要用手动 LIMIT否则 Pagehelper 会叠加一个 LIMIT导致数据变成“只查前 N 条之后的 N 条”这种错位结果。select idselectUserList resultTypecom.example.vo.UserVO select id, username, email, status, create_time from user where if testquery.username ! null and query.username ! and username like concat(%, #{query.username}, %) /if if testquery.status ! null and status #{query.status} /if /where order by create_time desc /select这段代码别小看它就是 Pagehelper 在 MyBatis Plus 项目里工作的标准范式。startPage之后紧接着的查询会被上分页其他查询不受影响。3.4 让 Pagehelper 和 MP 的分页插件共存的处理方式如果你的项目里已经配置了 MP 的PaginationInnerInterceptor并且你不想删掉它那 Pagehelper 仍然可以共存但有几个纪律必须遵守同一个查询只能走一种分页方式。要么用PageHelper.startPageselectList要么用Page参数 selectPage绝不能在一个查询上同时触发两套分页。Pagehelper 与 MP 分页拦截器可以按需拆分使用。比如核心业务列表用 MP 的selectPage复杂报表查询用 Pagehelper 兜底。这其实是一种很实际的分工MP 负责标准 CRUD 的分页Pagehelper 负责“疑难杂症” SQL 的分页。控制拦截器的执行顺序。如果你执意要让两者共存需要自定义ConfigurationCustomizer来控制 Interceptor 的注册顺序Configuration public class MybatisConfig { Bean public ConfigurationCustomizer mybatisConfigurationCustomizer() { return configuration - { // 确保 Pagehelper 优先于其他拦截器处理 }; } }但说实话踩过几次坑后我的建议是在同一个项目中分页的功能尽量收敛为一种方案。真遇到 Pagehelper 分页不了的极端 SQL再针对性处理而不是长期维护两套分页逻辑否则团队协作时很容易互相踩脚。4. 集成之后绕不开的坑我一个个说配置写好了、代码跑通了不等于就万事大吉。我在落地过程中遇到的几个典型问题值得单独拿出来讲透。4.1 场景 ABaseMapper.selectPage与 Pagehelper 的混乱前面说过MP 的BaseMapper自带了一个selectPage方法。这个方法的设计是配合 MP 分页插件使用的它期望Page作为参数传入。如果你在同一个方法里先调用了PageHelper.startPage然后又调用了selectPage会发生什么答案是Pagehelper 会把selectPage也当成一个普通查询去拦截而 MP 的selectPage又会根据Page对象再去拼一次 LIMIT。最终结果要么是 SQL 拼接错乱要么 count 查询异常。正确处理方式是明确区分两种写法。走 Pagehelper 时用selectList或自定义 XMLPageHelper.startPage(pageNum, pageSize); ListUser users userMapper.selectList(wrapper); PageInfoUser pageInfo new PageInfo(users);走 MP 自带分页时用selectPagePageUser page new Page(pageNum, pageSize); IPageUser result userMapper.selectPage(page, wrapper);这俩千万不要混着用。你可能觉得这只是“规范”问题但线上出现过因为某次重构同事在循环里误加了startPage导致后续所有接口第一次查询都被分页的严重问题。4.2 场景 Bcount 自动优化在复杂 SQL 下的意外Pagehelper 自动生成 count 查询时逻辑比较简单它会尝试把原始 SQL 改写成select count(0) from (原始SQL) table_count的形式。对于简单查询这没问题但对于包含 group by、distinct、union、多表 join 的复杂 SQL自动 count 可能会导致性能骤降。我遇到过一条带 group by 的报表 SQL原始查询 200ms 跑完Pagehelper 自动生成的 count 查询居然跑了 1.6 秒。原因就是它把整条 SQL 套了一层子查询让 MySQL 做了全量聚合后再 count。解决方案有两个第一种针对具体查询手工指定 countPageHelper.startPage(pageNum, pageSize); PageHelper.count(() - userMapper.countUserGroup(query)); ListUserVO list userMapper.selectUserGroup(query);第二种在 XML 里自定义 count SQL并在调用时增加countSuffix参数让 Pagehelper 使用指定的 count 方法。我实际项目里更倾向第二个方案因为它能让“count 走单独的轻量 SQL”成为团队规范而不是每个开发各自想办法。4.3 场景 C分页静默失效排查链路还原分页失效是 Pagehelper 最隐蔽的问题。代码没错、配置没错但结果就是不分页或者偶尔分页偶尔不分页。我复盘了一个真实案例。某个接口分页不定时失效。排查过程大致是先确认是否在同一个线程里开启了分页。如果startPage在子线程里调用而查询在主线程执行ThreadLocal 不共享分页自然不生效。再检查调用链里有没有Async。如果 Service 方法是异步执行的ThreadLocal 上下文就断了。期间还遇到过一个很经典的问题startPage之后执行查询之前中间穿插了其他耗时的远程调用由于无法保证同一个线程执行分页参数被清空查询走成了全量。最后定位到真正的原因——循环中多次调用startPage。某个批量导出功能在一个 for 循环里分批调用了分页查询每次都调PageHelper.startPage但最后一轮查询并不是紧跟着最新一次startPage的查询而是循环里其它节点上的查询导致这一节点被错误分页真正要分页的查询却因为 ThreadLocal 被后续调用覆盖而失效。这个问题的根治方式是让startPage和查询尽可能相邻并且保持在同一作用域内。不要在调用链中间穿插无关逻辑。如果团队里经常有人踩这个坑可以考虑封装统一的 PageQueryService把“启动分页 查询 收集结果”做成模板方法减少误用空间。4.4 场景 D嵌套结果映射导致的数据错位这是高级用法里最容易出问题的地方。当查询包含一对多关系时比如查订单列表同时要带出订单项很多人会写这样的结果映射resultMap idorderWithItems typecom.example.OrderVO id propertyid columnid/ collection propertyitems ofTypecom.example.OrderItemVO ... /collection /resultMap这种 N1 转嵌套结果的 SQL在分页时会出现一个尴尬情况Pagehelper 是对主查询的每行结果进行 LIMIT但 MyBatis 的嵌套结果映射会在内存里合并一对多数据导致合并后的行数和 SQL 返回的行数对不上。表现就是一页设置 10 条结果返回了 5 个订单因为有些订单带了两三条明细或者反过来明明订单有 8 条但页面只显示 5 条因为其中几条在上翻页时被“吃”掉了。处理这类问题业界公认的靠谱方案是先分页子查询再连表补全明细或者用collection的select属性走嵌套查询。Pagehelper 不背这个锅它只负责基于 SQL 结果行数分页理解这一点就能在设计 SQL 时主动避开“先合并再分页”的错误。5. 进阶结合 MyBatis Plus DDL 把分页玩成完整闭环最近“MyBatis Plus DDL”算是热词了很多人在讨论 MyBatis Plus 3.5.3 版本提供的动态 DDL 管理能力。用大白话说就是你可以通过 Java 代码直接创建表、修改表结构而不必手工去数据库执行脚本。这个能力配合 Pagehelper 的分页查询能非常优雅地解决一类常见需求管理后台的动态表单、报表、配置中心这类“数据表不固定”的业务场景。5.1 为什么这两者会走到一起过去我们做动态表单比如用户的客户可以自定义字段最粗暴的方案是先设计一张 EAV 表Entity-Attribute-Value一行一个属性。这种方式实现简单但查询性能很差字段多了以后 SQL 写起来想骂人。另一种方案是动态建表用户每创建一个新表单系统在后台CREATE TABLE一张物理表列结构由用户定义。这种方式查询性能好、符合业务直觉但需要付出表结构管理的成本。MyBatis Plus DDL 就补上这一环。表建好了下一步自然是列表展示默认要分页、搜索、排序。这时候 Pagehelper 的价值就体现出来了因为它不关心表名和列名是硬编码的还是运行时拼接的只要 SQL 在它就能分页。5.2 一个动态报表列表的完整实现假设现在要做一个“动态表单数据浏览”功能用户通过配置创建了一个名为form_customer_2025的表结构如下CREATE TABLE form_customer_2025 ( id bigint(20) NOT NULL AUTO_INCREMENT, customer_name varchar(100) DEFAULT NULL, phone varchar(20) DEFAULT NULL, created_at datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;在 MyBatis Plus 中可以使用 DDL 功能在代码里创建这张表这里不做过多展开核心思路是使用DDL相关 API 执行建表 SQL。建好之后分页查询就是典型的动态 SQL 场景表名、列名来自配置不能写死在 XML 里。这时可以用Select注解拼 SQL或者干脆构造一个动态SqlSource。我这里给一个用 MyBatis 注解方式的简单示例public interface DynamicFormMapper { Select(select * from ${tableName} where ${condition} order by id desc) ListMapString, Object queryFormData(Param(tableName) String tableName, Param(condition) String condition); }Service 层使用 Pagehelper 分页public PageResultMapString, Object pageFormData(String tableName, String condition, Integer pageNum, Integer pageSize) { PageHelper.startPage(pageNum, pageSize); ListMapString, Object dataList dynamicFormMapper.queryFormData(tableName, condition); PageInfoMapString, Object pageInfo new PageInfo(dataList); return PageResult.of(pageInfo.getList(), pageInfo.getTotal()); }这里有一个实操中很容易踩的雷动态表名拼接会导致 Pagehelper 生成的 count SQL 也要能正确解析表名。如果 condition 里有引号、特殊字符或者表名带了库名前缀count 查询可能因为 SQL 语法问题失败。我的建议是动态表名的场景下尽量保持 condition 简单或者单独配置countSql参数让 count 走一套更保险的 SQL。5.3 Pagehelper 对动态 SQL 场景的适配建议在动态 SQL 场景下使用 Pagehelper我总结了几条经验入参统一用 Map避免因为参数类型变化导致support-methods-arguments识别不到分页参数。尽量保证动态查询中order by是稳定存在的分页查询如果不排序翻页时数据会抖动用户看着像是在重复或丢数据。count 查询建议单独提供因为动态 SQL 的稳定性本来就差自动 count 再套一层子查询会放大风险。这个场景其实就是“MyBatis Plus 扩展方法”这个标题最好的落地诠释以 MP 作为数据访问的基础框架以 DDL 能力支撑动态表结构以 Pagehelper 补充分页查询的短板三者配合能覆盖很多常规 CRUD 框架搞不定的业务形态。写在最后的一点个人体会在实际项目里折腾完这一圈我最深的感受是技术选型永远没有“绝对正确”只有“当前阶段合适”。MyBatis Plus 自带分页对于规整的 CRUD 业务非常顺滑但 Pagehelper 这种老牌插件的生存能力强在“兜底能力”——不管业务 SQL 长什么样它都能按照预期去分页。这种兜底能力在复杂系统里的价值远比“少写一行代码”重要得多。如果你现在正准备在 MyBatis Plus 项目里接入 Pagehelper记住三件事一是依赖和版本尽量统一避免 MyBatis 版本冲突二是startPage和查询尽量写在一起中间不要插无关逻辑三是不要把两套分页搅在一起用定好规范团队少流汗。踩坑不可怕可怕的是坑就在那没人把它写在文档里。希望这篇内容能让你在走这条路时少翻几次车。
