1. 项目概述为什么MyBatisPlus分页是后端开发的“刚需”如果你用MyBatis做过列表查询大概率经历过这样的场景前端传过来一个页码page和每页大小size然后你在Mapper的XML里手写一个limit #{offset}, #{pageSize}。这活儿干一两次还行但项目里但凡有个三五张表需要分页重复的count查询和limit计算就能让你烦不胜烦。更别提那些带复杂多表关联和动态查询条件的列表了每次写分页逻辑都像在重复造轮子而且这个轮子还容易出错——比如count语句忘了加动态条件导致总数不对分页自然就乱了。这就是MyBatisPlus分页插件要解决的核心痛点将分页这一高频但繁琐的操作标准化、自动化。它不是一个可有可无的“甜点”功能而是提升后端开发效率、保证数据一致性的“基础设施”。简单来说它帮你把“计算总数、拼接limit、处理结果集”这一套流程封装起来你只需要关注核心的业务查询逻辑。我经历过从手写分页到使用插件的过程实测下来代码量能减少至少70%而且出错的概率大大降低。无论是简单的单表查询还是需要left join并附带一堆where条件的复杂场景这套机制都能稳稳接住。从网络热词里频繁出现的“接触mybatisplus单页500条限制”、“mybatisplus自动生成代码”也能看出大家在使用MyBatisPlus时分页和代码生成是最高频的两个需求点。今天我们就彻底把这个分页插件“扒开揉碎”从配置、使用、原理到避坑一次性讲透。无论你是刚接触Spring Boot和MyBatisPlus的新手还是想优化现有项目分页逻辑的老手这篇内容都能给你提供可直接“抄作业”的解决方案。2. 核心设计MyBatisPlus分页插件是如何工作的在动手配置之前我们得先弄明白这个插件到底在背后帮我们做了什么。知其然更要知其所以然这样出了问题你才知道从哪里下手排查。2.1 插件与拦截器MyBatis的扩展基石MyBatis本身提供了一个强大的插件机制准确说是基于拦截器Interceptor实现的。你可以编写一个类实现org.apache.ibatis.plugin.Interceptor接口然后在配置文件中声明它。这个拦截器可以拦截MyBatis执行过程中的四大核心对象的方法调用Executor(执行器)拦截增删改查的执行。StatementHandler(语句处理器)拦截SQL语句的构建和参数设置。ParameterHandler(参数处理器)拦截SQL参数的处理。ResultSetHandler(结果集处理器)拦截结果集的封装。MyBatisPlus的分页插件PaginationInnerInterceptor本质上就是一个这样的拦截器。它主要拦截的是Executor和StatementHandler。它的工作流程可以概括为以下几步拦截查询请求当你执行一个Mapper方法时如果该方法所在的接口继承了MyBatisPlus的BaseMapper并且你传入了Page对象作为参数插件就会识别这是一个分页查询请求。执行总数查询插件会“偷偷地”改造你的SQL。它先分析你的原始查询语句生成一条对应的COUNT(*)查询语句例如SELECT COUNT(*) FROM (你的原始SQL) tmp。然后用这条语句去数据库执行获取总记录数。这里有个关键点它会智能地优化COUNT查询比如自动去除原始的ORDER BY子句因为排序对总数计算无影响对于复杂的联表查询也可能有特定的优化策略。改造原始SQL拿到总数后插件会根据你传入的Page对象中的当前页码current和每页大小size计算出偏移量offset。然后利用数据库方言Dialect将你的原始SQL改造成包含LIMIT offset, sizeMySQL或等价的方言语句。执行分页查询并封装结果执行改造后的分页SQL获取当前页的数据。最后插件将当前页数据列表和查询到的总记录数一起封装回你传入的那个Page对象中完成整个过程。整个过程对开发者是透明的你只需要关心“我要查第几页每页多少条”以及“我的查询条件是什么”。这种设计完美体现了“约定大于配置”的思想。2.2 配置背后的考量性能、安全与灵活性理解了原理再看配置项你就明白为什么这么设计了。以最新的MybatisPlusInterceptor聚合拦截器配置方式为例Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 1. 添加分页插件 PaginationInnerInterceptor paginationInnerInterceptor new PaginationInnerInterceptor(DbType.MYSQL); // 设置请求的页面大于最大页后操作 true调回到首页false 继续请求 默认false paginationInnerInterceptor.setOverflow(false); // 设置最大单页限制数量默认 500 条-1 不受限制 paginationInnerInterceptor.setMaxLimit(500L); // 开启 count 的 join 优化,只针对部分 left join paginationInnerInterceptor.setOptimizeJoin(true); interceptor.addInnerInterceptor(paginationInnerInterceptor); // 2. 可以继续添加其他插件比如乐观锁插件、防止全表更新与删除插件 // interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); // interceptor.addInnerInterceptor(new BlockAttackInnerInterceptor()); return interceptor; } }DbType.MYSQL这是必须指定的。因为不同数据库MySQL, Oracle, PostgreSQL等的分页语法截然不同。告诉插件数据库类型它才能生成正确的分页SQL。这是插件兼容多数据库的基础。setOverflow(false)这是一个安全/体验策略。假设总共有10页用户请求了第100页。如果overflow为true插件会自动将查询重置到首页第1页。如果为false则会返回一个空的数据列表。通常设为false由前端来处理超出范围的页码请求更合适。setMaxLimit(500L)这是从热词“接触mybatisplus单页500条限制”来的关键配置默认就是500。它的作用是防止前端或调用方传入一个巨大的size比如10000导致单次查询拖垮数据库。即使前端传了size10000实际查询也会被限制为500条。你可以根据系统性能调整这个值如果设置为-1则禁用限制。我强烈建议不要设为-1必须要有这个兜底。setOptimizeJoin(true)这是一个性能优化项。当你的分页查询是left join且where条件只涉及主表时开启此优化插件会尝试将count查询优化为只对主表进行计数可以大幅提升count速度。但注意如果where条件涉及关联表此优化可能不生效或导致错误需要根据实际情况测试。注意这里有一个版本差异带来的巨大“坑点”。如果你用的是Spring Boot 3.x对应热词中的springboot3并且MyBatisPlus版本在3.5.3之前在配置上可能会遇到问题。因为Spring Boot 3使用了Jakarta EE 9包名从javax改为了jakarta。老版本的MP可能与之不兼容。务必确保你的MyBatisPlus版本在3.5.3及以上官方在这个版本做了对Spring Boot 3的适配。这是整合时第一个要检查的地方。3. 从入门到精通分页插件的三种使用姿势配置好插件我们就可以在Service或Controller中使用了。根据不同的业务场景我总结了三种最常用、最清晰的使用方式。3.1 基础用法Page对象与BaseMapper的完美配合这是最直接、最经典的方式适用于绝大多数简单的单表或多表查询。Service public class UserServiceImpl extends ServiceImplUserMapper, User implements IUserService { Override public PageUser getUserPage(PageQuery query) { // 1. 构建分页条件 PageUser page new Page(query.getCurrent(), query.getSize()); // 2. 构建查询条件使用QueryWrapper或LambdaQueryWrapper LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.isNotBlank(query.getName()), User::getName, query.getName()) .eq(query.getStatus() ! null, User::getStatus, query.getStatus()) .orderByDesc(User::getCreateTime); // 3. 执行分页查询 return baseMapper.selectPage(page, wrapper); } } // 简单的查询参数封装 Data public class PageQuery { private Long current 1L; // 当前页默认第一页 private Long size 10L; // 每页大小默认10条 private String name; private Integer status; }执行后page对象里不仅包含当前页的数据列表(page.getRecords())还包含了总数(page.getTotal())、总页数(page.getPages())。前端拿到这个对象渲染数据和分页器就都有了依据。实操心得new Page(current, size)中的current起始页是1不是0。这是为了更符合业务人员的习惯。强烈推荐使用LambdaQueryWrapper它利用方法引用来构建条件如User::getName能有效避免因手写字段名字符串“name”而导致的拼写错误这在重构时尤其安全。分页查询会自动执行COUNT(1)语句。如果你的表数据量非常大千万级以上复杂的COUNT可能会慢。这时需要考虑后续会讲到的优化方案。3.2 进阶用法在自定义Mapper方法中实现分页业务不可能总是简单的单表查询。当我们需要编写复杂的自定义SQL在XML中或使用Select注解时分页插件同样能发挥作用。第一步在Mapper接口中定义方法第一个参数必须是Page类型public interface UserMapper extends BaseMapperUser { // 自定义分页查询查询用户及其部门名称 PageUserVO selectUserPage(Param(page) PageUserVO page, Param(query) UserPageQuery query); }第二步在对应的XML文件中编写SQL。注意你只需要写查询数据的SQL不需要写limit和count语句!-- UserMapper.xml -- select idselectUserPage resultTypecom.example.vo.UserVO SELECT u.*, d.dept_name FROM user u LEFT JOIN department d ON u.dept_id d.id where if testquery.userName ! null and query.userName ! AND u.name LIKE CONCAT(%, #{query.userName}, %) /if if testquery.deptId ! null AND u.dept_id #{query.deptId} /if /where ORDER BY u.create_time DESC !-- 不要在这里写 LIMIT插件会自动处理 -- /select第三步在Service中调用Override public PageUserVO getUserPageWithDept(UserPageQuery query) { PageUserVO page new Page(query.getCurrent(), query.getSize()); return userMapper.selectUserPage(page, query); }为什么这样可行因为分页插件会拦截这个Mapper方法的执行。它发现第一个参数是Page对象于是动态生成一条SELECT COUNT(*) FROM (你的完整SQL) tmp_count语句去执行获取total。根据数据库方言为你的原始SQL末尾加上LIMIT #{offset}, #{size}。执行拼接后的SQL获取当前页数据。将数据和总数塞回Page对象。避坑指南这是最容易出错的地方。很多新手会在XML里自己写LIMIT导致插件再次添加LIMITSQL报错。记住只要参数里有Page对象XML里就绝对不要出现limit、rownum等分页关键字3.3 高阶用法手动分页与特定优化有些极端场景下你可能需要更精细的控制。场景一不需要总数只取一页数据例如移动端下拉加载更多频繁的COUNT在高并发下是负担。如果业务不关心总条数只关心“还有没有下一页”可以使用Page的setSearchCount(false)方法。Override public ListUser getNextPage(Long lastId, Long size) { PageUser page new Page(1, size); // current此时无意义 page.setSearchCount(false); // 关键告诉插件不要执行COUNT查询 LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.gt(User::getId, lastId) // 基于上次最后一条ID查询 .orderByAsc(User::getId); return baseMapper.selectPage(page, wrapper).getRecords(); } // 前端判断如果返回的列表长度 size说明没有更多数据了。场景二超大数据表的COUNT优化对于数千万行且条件复杂的表SELECT COUNT(*)可能极慢。一个常见的优化方案是用setSearchCount(false)关闭自动Count。用Redis或别的缓存系统缓存一个估算的、或定期更新的总行数。对于很多列表页一个近似值甚至是“10万”这样的量级就足够了。如果必须精确计数考虑使用覆盖索引或数据库的近似行数统计如MySQL的SHOW TABLE STATUS但注意不精确。Override public PageUser getLargeTablePage(PageQuery query) { PageUser page new Page(query.getCurrent(), query.getSize()); // 1. 首先尝试从缓存获取总数 Long total redisTemplate.opsForValue().get(user_table_count); if (total null) { // 2. 缓存没有执行一次性的可能较慢的精确计数并放入缓存设置过期时间 page.setSearchCount(true); // 本次需要计数 this.page(page, wrapper); total page.getTotal(); redisTemplate.opsForValue().set(user_table_count, total, 10, TimeUnit.MINUTES); } else { // 3. 使用缓存的总数并关闭本次查询的计数 page.setSearchCount(false); this.page(page, wrapper); // 只查数据 page.setTotal(total); // 手动设置总数 } return page; }4. 实战问题排查与性能调优记录理论配置和基础用法都跑通了但在真实项目里你一定会遇到各种稀奇古怪的问题。下面是我和团队在实际开发中踩过的坑和总结的解决方案。4.1 常见问题速查表问题现象可能原因解决方案分页查询结果总数total为0但实际有数据1. 自定义SQL中Page参数未使用Param(“page”)注解。2. 多参数方法中Page参数不是第一个参数。1. 确保Mapper方法中分页参数有Param(“page”)。2. 将Page参数调整为方法第一个参数。SQL语法错误提示LIMIT附近有错误1. 在XML自定义SQL中自己写了LIMIT。2. 数据库方言DbType配置错误例如配成了MySQL但连的是Oracle。1. 检查并删除XML中的LIMIT子句。2. 检查PaginationInnerInterceptor构造器传入的DbType是否与实际数据库匹配。COUNT语句执行异常或很慢1. SQL过于复杂嵌套子查询或多个LEFT JOIN导致COUNT优化失败。2. 表数据量巨大且WHERE条件字段无索引。1. 尝试关闭setOptimizeJoin(true)看是否正常。2. 考虑使用4.2节的count查询优化或使用4.3节的缓存方案。返回的Page对象中records为空但total不为0请求的页码current超出了最大页数pages。检查前端传递的页码参数。根据setOverflow的配置要么返回空列表要么回到首页。应在业务逻辑或前端进行校验。升级到Spring Boot 3后分页插件失效MyBatisPlus版本过旧低于3.5.3与Jakarta EE不兼容。将MyBatisPlus依赖升级到3.5.3或更高版本。多租户Tenant或数据权限插件与分页插件冲突拦截器执行顺序问题。分页插件可能在其他插件修改SQL前就执行了COUNT。在配置MybatisPlusInterceptor时注意添加拦截器的顺序。通常顺序应为多租户-动态表名-分页-乐观锁-防止全表更新。将分页插件放在靠后的位置。4.2 深度优化自定义COUNT查询与复杂SQL处理当自动生成的COUNT语句效率低下或出错时常见于带有GROUP BY或多个UNION的复杂查询MyBatisPlus提供了自定义COUNT查询的逃生通道。你可以在Mapper接口的同名方法上使用InterceptorIgnore注解来告诉插件“这个方法的COUNT语句我自己来”。第一步在Mapper中定义两个方法一个查数据一个查总数。public interface ComplexReportMapper extends BaseMapperOrder { // 主查询方法 PageOrderReportVO selectComplexReport(Param(page) PageOrderReportVO page, Param(query) ReportQuery query); // 自定义的COUNT查询方法方法名必须是 方法名_COUNT 的格式 Long selectComplexReport_COUNT(Param(query) ReportQuery query); }第二步在XML中分别实现这两个SQL。select idselectComplexReport resultTypecom.example.vo.OrderReportVO SELECT user_id, product_id, SUM(amount) as total_amount, COUNT(*) as order_count FROM order WHERE create_time BETWEEN #{query.startTime} AND #{query.endTime} GROUP BY user_id, product_id ORDER BY total_amount DESC !-- 依然不要写LIMIT -- /select select idselectComplexReport_COUNT resultTypejava.lang.Long !-- 这里编写一个高效、简化的COUNT查询 -- SELECT COUNT(DISTINCT user_id, product_id) FROM order WHERE create_time BETWEEN #{query.startTime} AND #{query.endTime} /select插件会智能地发现存在selectComplexReport_COUNT方法从而放弃自动生成COUNT语句转而调用你这个自定义的方法。这给了你最大的灵活性去优化计数逻辑。4.3 性能监控与“500条限制”的权衡热词里提到了“接触mybatisplus单页500条限制”这其实是一个很好的安全阀。但在内部管理系统或数据导出场景有时确实需要突破这个限制。方案一临时调整MaxLimit不推荐在生产环境开放可以在某个特定接口的业务代码里动态创建一个新的Page对象并利用其setMaxLimit方法注意此方法在Page对象上仅对该次查询生效不影响全局配置。public PageData exportData(ExportQuery query) { PageData page new Page(query.getCurrent(), query.getSize()); // 仅本次查询允许更大的分页 page.setMaxLimit(5000L); return baseMapper.selectPage(page, wrapper); }方案二绕过分页插件手动分页推荐用于大数据导出对于数据导出这种“读全量数据”的场景更常见的做法是使用流式查询避免一次性加载海量数据导致OOM。这时就需要绕过分页插件。Autowired private SqlSessionFactory sqlSessionFactory; public void exportLargeData(OutputStream os) { try (SqlSession sqlSession sqlSessionFactory.openSession(ExecutorType.SIMPLE); CursorData cursor sqlSession.selectCursor(com.example.mapper.DataMapper.selectAllForExport)) { // 使用游标逐条处理数据并写入输出流 for (Data data : cursor) { // ... 处理并写入data到os ... } } catch (Exception e) { // 处理异常 } } // 在Mapper.xml中selectAllForExport就是一个普通的select没有limit监控建议在全局配置中务必保留setMaxLimit(500L)。同时在日志中监控SQL执行时间对超过一定阈值如2秒的查询进行告警特别是分页查询。可以使用p6spy或druid等数据源监控工具来达成。5. 与Spring Boot 3及现代技术栈的整合要点结合热词中提到的springboot3和mybatisplus整合kafuka记录日志等现代项目往往不是孤立的。分页作为数据访问层的基础功能需要与整个技术栈和谐共处。1. 依赖版本对齐Spring Boot 3 MyBatisPlus 3.5.3这是整合成功的前提。在你的pom.xml中确保版本匹配properties spring-boot.version3.1.5/spring-boot.version mybatis-plus.version3.5.4/mybatis-plus.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version${mybatis-plus.version}/version /dependency /dependencies2. 统一分页响应体设计前后端分离项目中需要一个固定的数据结构来包装分页结果。我常用的格式如下Data public class PageResultT { private Long current; private Long size; private Long total; private Long pages; private ListT records; // 快速从MyBatisPlus的Page对象转换 public static T PageResultT success(PageT page) { PageResultT result new PageResult(); result.setCurrent(page.getCurrent()); result.setSize(page.getSize()); result.setTotal(page.getTotal()); result.setPages(page.getPages()); result.setRecords(page.getRecords()); return result; } } // Controller中 GetMapping(/page) public RPageResultUserVO getUserPage(PageQuery query) { PageUserVO page userService.getUserPage(query); return R.success(PageResult.success(page)); }3. 结合AOP记录分页查询日志热词aop使用场景你想知道哪些接口的分页查询最慢吗用AOP轻松实现。Aspect Component Slf4j public class PageQueryLogAspect { // 拦截所有Service层方法且方法第一个参数是Page类型 Around(execution(* com.example..service..*.*(com.baomidou.mybatisplus.extension.plugins.pagination.Page, ..))) public Object logPageQuery(ProceedingJoinPoint joinPoint) throws Throwable { Object[] args joinPoint.getArgs(); Page? pageParam null; for (Object arg : args) { if (arg instanceof Page) { pageParam (Page?) arg; break; } } long startTime System.currentTimeMillis(); Object result joinPoint.proceed(); // 执行原方法 long costTime System.currentTimeMillis() - startTime; if (pageParam ! null result instanceof Page) { Page? pageResult (Page?) result; log.info(分页查询日志 - 方法: {}, 页码: {}, 大小: {}, 总数: {}, 耗时: {}ms, joinPoint.getSignature().toShortString(), pageParam.getCurrent(), pageParam.getSize(), pageResult.getTotal(), costTime); // 如果耗时过长可以触发告警如发送到Kafka热词mybatisplus整合kafuka记录日志 if (costTime 1000) { // 超过1秒视为慢查询 // kafkaTemplate.send(slow-query-log, logMessage); } } return result; } }4. 谨慎处理“单页500条限制”的突破请求如果有业务方如数据分析团队请求临时调大MaxLimit以导出数据一定要有审批和监控流程。最好提供一个独立的、有权限控制的“数据导出”接口该接口使用独立的、限制更宽松的数据源配置或手动流式查询而不是直接修改核心业务服务的全局配置。配置和使用MyBatisPlus分页插件从“能用”到“用好”关键就在于理解其工作原理并根据实际业务场景进行微调和优化。它就像给你的数据查询引擎加装了一个自动变速箱让高频、重复的分页操作变得平滑顺畅。把今天提到的配置模板、三种用法、问题排查表和优化技巧融入到你的项目中你就能构建出一个既高效又稳健的数据访问层。
MyBatisPlus分页插件深度解析：从原理、配置到性能优化实战
1. 项目概述为什么MyBatisPlus分页是后端开发的“刚需”如果你用MyBatis做过列表查询大概率经历过这样的场景前端传过来一个页码page和每页大小size然后你在Mapper的XML里手写一个limit #{offset}, #{pageSize}。这活儿干一两次还行但项目里但凡有个三五张表需要分页重复的count查询和limit计算就能让你烦不胜烦。更别提那些带复杂多表关联和动态查询条件的列表了每次写分页逻辑都像在重复造轮子而且这个轮子还容易出错——比如count语句忘了加动态条件导致总数不对分页自然就乱了。这就是MyBatisPlus分页插件要解决的核心痛点将分页这一高频但繁琐的操作标准化、自动化。它不是一个可有可无的“甜点”功能而是提升后端开发效率、保证数据一致性的“基础设施”。简单来说它帮你把“计算总数、拼接limit、处理结果集”这一套流程封装起来你只需要关注核心的业务查询逻辑。我经历过从手写分页到使用插件的过程实测下来代码量能减少至少70%而且出错的概率大大降低。无论是简单的单表查询还是需要left join并附带一堆where条件的复杂场景这套机制都能稳稳接住。从网络热词里频繁出现的“接触mybatisplus单页500条限制”、“mybatisplus自动生成代码”也能看出大家在使用MyBatisPlus时分页和代码生成是最高频的两个需求点。今天我们就彻底把这个分页插件“扒开揉碎”从配置、使用、原理到避坑一次性讲透。无论你是刚接触Spring Boot和MyBatisPlus的新手还是想优化现有项目分页逻辑的老手这篇内容都能给你提供可直接“抄作业”的解决方案。2. 核心设计MyBatisPlus分页插件是如何工作的在动手配置之前我们得先弄明白这个插件到底在背后帮我们做了什么。知其然更要知其所以然这样出了问题你才知道从哪里下手排查。2.1 插件与拦截器MyBatis的扩展基石MyBatis本身提供了一个强大的插件机制准确说是基于拦截器Interceptor实现的。你可以编写一个类实现org.apache.ibatis.plugin.Interceptor接口然后在配置文件中声明它。这个拦截器可以拦截MyBatis执行过程中的四大核心对象的方法调用Executor(执行器)拦截增删改查的执行。StatementHandler(语句处理器)拦截SQL语句的构建和参数设置。ParameterHandler(参数处理器)拦截SQL参数的处理。ResultSetHandler(结果集处理器)拦截结果集的封装。MyBatisPlus的分页插件PaginationInnerInterceptor本质上就是一个这样的拦截器。它主要拦截的是Executor和StatementHandler。它的工作流程可以概括为以下几步拦截查询请求当你执行一个Mapper方法时如果该方法所在的接口继承了MyBatisPlus的BaseMapper并且你传入了Page对象作为参数插件就会识别这是一个分页查询请求。执行总数查询插件会“偷偷地”改造你的SQL。它先分析你的原始查询语句生成一条对应的COUNT(*)查询语句例如SELECT COUNT(*) FROM (你的原始SQL) tmp。然后用这条语句去数据库执行获取总记录数。这里有个关键点它会智能地优化COUNT查询比如自动去除原始的ORDER BY子句因为排序对总数计算无影响对于复杂的联表查询也可能有特定的优化策略。改造原始SQL拿到总数后插件会根据你传入的Page对象中的当前页码current和每页大小size计算出偏移量offset。然后利用数据库方言Dialect将你的原始SQL改造成包含LIMIT offset, sizeMySQL或等价的方言语句。执行分页查询并封装结果执行改造后的分页SQL获取当前页的数据。最后插件将当前页数据列表和查询到的总记录数一起封装回你传入的那个Page对象中完成整个过程。整个过程对开发者是透明的你只需要关心“我要查第几页每页多少条”以及“我的查询条件是什么”。这种设计完美体现了“约定大于配置”的思想。2.2 配置背后的考量性能、安全与灵活性理解了原理再看配置项你就明白为什么这么设计了。以最新的MybatisPlusInterceptor聚合拦截器配置方式为例Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 1. 添加分页插件 PaginationInnerInterceptor paginationInnerInterceptor new PaginationInnerInterceptor(DbType.MYSQL); // 设置请求的页面大于最大页后操作 true调回到首页false 继续请求 默认false paginationInnerInterceptor.setOverflow(false); // 设置最大单页限制数量默认 500 条-1 不受限制 paginationInnerInterceptor.setMaxLimit(500L); // 开启 count 的 join 优化,只针对部分 left join paginationInnerInterceptor.setOptimizeJoin(true); interceptor.addInnerInterceptor(paginationInnerInterceptor); // 2. 可以继续添加其他插件比如乐观锁插件、防止全表更新与删除插件 // interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); // interceptor.addInnerInterceptor(new BlockAttackInnerInterceptor()); return interceptor; } }DbType.MYSQL这是必须指定的。因为不同数据库MySQL, Oracle, PostgreSQL等的分页语法截然不同。告诉插件数据库类型它才能生成正确的分页SQL。这是插件兼容多数据库的基础。setOverflow(false)这是一个安全/体验策略。假设总共有10页用户请求了第100页。如果overflow为true插件会自动将查询重置到首页第1页。如果为false则会返回一个空的数据列表。通常设为false由前端来处理超出范围的页码请求更合适。setMaxLimit(500L)这是从热词“接触mybatisplus单页500条限制”来的关键配置默认就是500。它的作用是防止前端或调用方传入一个巨大的size比如10000导致单次查询拖垮数据库。即使前端传了size10000实际查询也会被限制为500条。你可以根据系统性能调整这个值如果设置为-1则禁用限制。我强烈建议不要设为-1必须要有这个兜底。setOptimizeJoin(true)这是一个性能优化项。当你的分页查询是left join且where条件只涉及主表时开启此优化插件会尝试将count查询优化为只对主表进行计数可以大幅提升count速度。但注意如果where条件涉及关联表此优化可能不生效或导致错误需要根据实际情况测试。注意这里有一个版本差异带来的巨大“坑点”。如果你用的是Spring Boot 3.x对应热词中的springboot3并且MyBatisPlus版本在3.5.3之前在配置上可能会遇到问题。因为Spring Boot 3使用了Jakarta EE 9包名从javax改为了jakarta。老版本的MP可能与之不兼容。务必确保你的MyBatisPlus版本在3.5.3及以上官方在这个版本做了对Spring Boot 3的适配。这是整合时第一个要检查的地方。3. 从入门到精通分页插件的三种使用姿势配置好插件我们就可以在Service或Controller中使用了。根据不同的业务场景我总结了三种最常用、最清晰的使用方式。3.1 基础用法Page对象与BaseMapper的完美配合这是最直接、最经典的方式适用于绝大多数简单的单表或多表查询。Service public class UserServiceImpl extends ServiceImplUserMapper, User implements IUserService { Override public PageUser getUserPage(PageQuery query) { // 1. 构建分页条件 PageUser page new Page(query.getCurrent(), query.getSize()); // 2. 构建查询条件使用QueryWrapper或LambdaQueryWrapper LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.isNotBlank(query.getName()), User::getName, query.getName()) .eq(query.getStatus() ! null, User::getStatus, query.getStatus()) .orderByDesc(User::getCreateTime); // 3. 执行分页查询 return baseMapper.selectPage(page, wrapper); } } // 简单的查询参数封装 Data public class PageQuery { private Long current 1L; // 当前页默认第一页 private Long size 10L; // 每页大小默认10条 private String name; private Integer status; }执行后page对象里不仅包含当前页的数据列表(page.getRecords())还包含了总数(page.getTotal())、总页数(page.getPages())。前端拿到这个对象渲染数据和分页器就都有了依据。实操心得new Page(current, size)中的current起始页是1不是0。这是为了更符合业务人员的习惯。强烈推荐使用LambdaQueryWrapper它利用方法引用来构建条件如User::getName能有效避免因手写字段名字符串“name”而导致的拼写错误这在重构时尤其安全。分页查询会自动执行COUNT(1)语句。如果你的表数据量非常大千万级以上复杂的COUNT可能会慢。这时需要考虑后续会讲到的优化方案。3.2 进阶用法在自定义Mapper方法中实现分页业务不可能总是简单的单表查询。当我们需要编写复杂的自定义SQL在XML中或使用Select注解时分页插件同样能发挥作用。第一步在Mapper接口中定义方法第一个参数必须是Page类型public interface UserMapper extends BaseMapperUser { // 自定义分页查询查询用户及其部门名称 PageUserVO selectUserPage(Param(page) PageUserVO page, Param(query) UserPageQuery query); }第二步在对应的XML文件中编写SQL。注意你只需要写查询数据的SQL不需要写limit和count语句!-- UserMapper.xml -- select idselectUserPage resultTypecom.example.vo.UserVO SELECT u.*, d.dept_name FROM user u LEFT JOIN department d ON u.dept_id d.id where if testquery.userName ! null and query.userName ! AND u.name LIKE CONCAT(%, #{query.userName}, %) /if if testquery.deptId ! null AND u.dept_id #{query.deptId} /if /where ORDER BY u.create_time DESC !-- 不要在这里写 LIMIT插件会自动处理 -- /select第三步在Service中调用Override public PageUserVO getUserPageWithDept(UserPageQuery query) { PageUserVO page new Page(query.getCurrent(), query.getSize()); return userMapper.selectUserPage(page, query); }为什么这样可行因为分页插件会拦截这个Mapper方法的执行。它发现第一个参数是Page对象于是动态生成一条SELECT COUNT(*) FROM (你的完整SQL) tmp_count语句去执行获取total。根据数据库方言为你的原始SQL末尾加上LIMIT #{offset}, #{size}。执行拼接后的SQL获取当前页数据。将数据和总数塞回Page对象。避坑指南这是最容易出错的地方。很多新手会在XML里自己写LIMIT导致插件再次添加LIMITSQL报错。记住只要参数里有Page对象XML里就绝对不要出现limit、rownum等分页关键字3.3 高阶用法手动分页与特定优化有些极端场景下你可能需要更精细的控制。场景一不需要总数只取一页数据例如移动端下拉加载更多频繁的COUNT在高并发下是负担。如果业务不关心总条数只关心“还有没有下一页”可以使用Page的setSearchCount(false)方法。Override public ListUser getNextPage(Long lastId, Long size) { PageUser page new Page(1, size); // current此时无意义 page.setSearchCount(false); // 关键告诉插件不要执行COUNT查询 LambdaQueryWrapperUser wrapper new LambdaQueryWrapper(); wrapper.gt(User::getId, lastId) // 基于上次最后一条ID查询 .orderByAsc(User::getId); return baseMapper.selectPage(page, wrapper).getRecords(); } // 前端判断如果返回的列表长度 size说明没有更多数据了。场景二超大数据表的COUNT优化对于数千万行且条件复杂的表SELECT COUNT(*)可能极慢。一个常见的优化方案是用setSearchCount(false)关闭自动Count。用Redis或别的缓存系统缓存一个估算的、或定期更新的总行数。对于很多列表页一个近似值甚至是“10万”这样的量级就足够了。如果必须精确计数考虑使用覆盖索引或数据库的近似行数统计如MySQL的SHOW TABLE STATUS但注意不精确。Override public PageUser getLargeTablePage(PageQuery query) { PageUser page new Page(query.getCurrent(), query.getSize()); // 1. 首先尝试从缓存获取总数 Long total redisTemplate.opsForValue().get(user_table_count); if (total null) { // 2. 缓存没有执行一次性的可能较慢的精确计数并放入缓存设置过期时间 page.setSearchCount(true); // 本次需要计数 this.page(page, wrapper); total page.getTotal(); redisTemplate.opsForValue().set(user_table_count, total, 10, TimeUnit.MINUTES); } else { // 3. 使用缓存的总数并关闭本次查询的计数 page.setSearchCount(false); this.page(page, wrapper); // 只查数据 page.setTotal(total); // 手动设置总数 } return page; }4. 实战问题排查与性能调优记录理论配置和基础用法都跑通了但在真实项目里你一定会遇到各种稀奇古怪的问题。下面是我和团队在实际开发中踩过的坑和总结的解决方案。4.1 常见问题速查表问题现象可能原因解决方案分页查询结果总数total为0但实际有数据1. 自定义SQL中Page参数未使用Param(“page”)注解。2. 多参数方法中Page参数不是第一个参数。1. 确保Mapper方法中分页参数有Param(“page”)。2. 将Page参数调整为方法第一个参数。SQL语法错误提示LIMIT附近有错误1. 在XML自定义SQL中自己写了LIMIT。2. 数据库方言DbType配置错误例如配成了MySQL但连的是Oracle。1. 检查并删除XML中的LIMIT子句。2. 检查PaginationInnerInterceptor构造器传入的DbType是否与实际数据库匹配。COUNT语句执行异常或很慢1. SQL过于复杂嵌套子查询或多个LEFT JOIN导致COUNT优化失败。2. 表数据量巨大且WHERE条件字段无索引。1. 尝试关闭setOptimizeJoin(true)看是否正常。2. 考虑使用4.2节的count查询优化或使用4.3节的缓存方案。返回的Page对象中records为空但total不为0请求的页码current超出了最大页数pages。检查前端传递的页码参数。根据setOverflow的配置要么返回空列表要么回到首页。应在业务逻辑或前端进行校验。升级到Spring Boot 3后分页插件失效MyBatisPlus版本过旧低于3.5.3与Jakarta EE不兼容。将MyBatisPlus依赖升级到3.5.3或更高版本。多租户Tenant或数据权限插件与分页插件冲突拦截器执行顺序问题。分页插件可能在其他插件修改SQL前就执行了COUNT。在配置MybatisPlusInterceptor时注意添加拦截器的顺序。通常顺序应为多租户-动态表名-分页-乐观锁-防止全表更新。将分页插件放在靠后的位置。4.2 深度优化自定义COUNT查询与复杂SQL处理当自动生成的COUNT语句效率低下或出错时常见于带有GROUP BY或多个UNION的复杂查询MyBatisPlus提供了自定义COUNT查询的逃生通道。你可以在Mapper接口的同名方法上使用InterceptorIgnore注解来告诉插件“这个方法的COUNT语句我自己来”。第一步在Mapper中定义两个方法一个查数据一个查总数。public interface ComplexReportMapper extends BaseMapperOrder { // 主查询方法 PageOrderReportVO selectComplexReport(Param(page) PageOrderReportVO page, Param(query) ReportQuery query); // 自定义的COUNT查询方法方法名必须是 方法名_COUNT 的格式 Long selectComplexReport_COUNT(Param(query) ReportQuery query); }第二步在XML中分别实现这两个SQL。select idselectComplexReport resultTypecom.example.vo.OrderReportVO SELECT user_id, product_id, SUM(amount) as total_amount, COUNT(*) as order_count FROM order WHERE create_time BETWEEN #{query.startTime} AND #{query.endTime} GROUP BY user_id, product_id ORDER BY total_amount DESC !-- 依然不要写LIMIT -- /select select idselectComplexReport_COUNT resultTypejava.lang.Long !-- 这里编写一个高效、简化的COUNT查询 -- SELECT COUNT(DISTINCT user_id, product_id) FROM order WHERE create_time BETWEEN #{query.startTime} AND #{query.endTime} /select插件会智能地发现存在selectComplexReport_COUNT方法从而放弃自动生成COUNT语句转而调用你这个自定义的方法。这给了你最大的灵活性去优化计数逻辑。4.3 性能监控与“500条限制”的权衡热词里提到了“接触mybatisplus单页500条限制”这其实是一个很好的安全阀。但在内部管理系统或数据导出场景有时确实需要突破这个限制。方案一临时调整MaxLimit不推荐在生产环境开放可以在某个特定接口的业务代码里动态创建一个新的Page对象并利用其setMaxLimit方法注意此方法在Page对象上仅对该次查询生效不影响全局配置。public PageData exportData(ExportQuery query) { PageData page new Page(query.getCurrent(), query.getSize()); // 仅本次查询允许更大的分页 page.setMaxLimit(5000L); return baseMapper.selectPage(page, wrapper); }方案二绕过分页插件手动分页推荐用于大数据导出对于数据导出这种“读全量数据”的场景更常见的做法是使用流式查询避免一次性加载海量数据导致OOM。这时就需要绕过分页插件。Autowired private SqlSessionFactory sqlSessionFactory; public void exportLargeData(OutputStream os) { try (SqlSession sqlSession sqlSessionFactory.openSession(ExecutorType.SIMPLE); CursorData cursor sqlSession.selectCursor(com.example.mapper.DataMapper.selectAllForExport)) { // 使用游标逐条处理数据并写入输出流 for (Data data : cursor) { // ... 处理并写入data到os ... } } catch (Exception e) { // 处理异常 } } // 在Mapper.xml中selectAllForExport就是一个普通的select没有limit监控建议在全局配置中务必保留setMaxLimit(500L)。同时在日志中监控SQL执行时间对超过一定阈值如2秒的查询进行告警特别是分页查询。可以使用p6spy或druid等数据源监控工具来达成。5. 与Spring Boot 3及现代技术栈的整合要点结合热词中提到的springboot3和mybatisplus整合kafuka记录日志等现代项目往往不是孤立的。分页作为数据访问层的基础功能需要与整个技术栈和谐共处。1. 依赖版本对齐Spring Boot 3 MyBatisPlus 3.5.3这是整合成功的前提。在你的pom.xml中确保版本匹配properties spring-boot.version3.1.5/spring-boot.version mybatis-plus.version3.5.4/mybatis-plus.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version${mybatis-plus.version}/version /dependency /dependencies2. 统一分页响应体设计前后端分离项目中需要一个固定的数据结构来包装分页结果。我常用的格式如下Data public class PageResultT { private Long current; private Long size; private Long total; private Long pages; private ListT records; // 快速从MyBatisPlus的Page对象转换 public static T PageResultT success(PageT page) { PageResultT result new PageResult(); result.setCurrent(page.getCurrent()); result.setSize(page.getSize()); result.setTotal(page.getTotal()); result.setPages(page.getPages()); result.setRecords(page.getRecords()); return result; } } // Controller中 GetMapping(/page) public RPageResultUserVO getUserPage(PageQuery query) { PageUserVO page userService.getUserPage(query); return R.success(PageResult.success(page)); }3. 结合AOP记录分页查询日志热词aop使用场景你想知道哪些接口的分页查询最慢吗用AOP轻松实现。Aspect Component Slf4j public class PageQueryLogAspect { // 拦截所有Service层方法且方法第一个参数是Page类型 Around(execution(* com.example..service..*.*(com.baomidou.mybatisplus.extension.plugins.pagination.Page, ..))) public Object logPageQuery(ProceedingJoinPoint joinPoint) throws Throwable { Object[] args joinPoint.getArgs(); Page? pageParam null; for (Object arg : args) { if (arg instanceof Page) { pageParam (Page?) arg; break; } } long startTime System.currentTimeMillis(); Object result joinPoint.proceed(); // 执行原方法 long costTime System.currentTimeMillis() - startTime; if (pageParam ! null result instanceof Page) { Page? pageResult (Page?) result; log.info(分页查询日志 - 方法: {}, 页码: {}, 大小: {}, 总数: {}, 耗时: {}ms, joinPoint.getSignature().toShortString(), pageParam.getCurrent(), pageParam.getSize(), pageResult.getTotal(), costTime); // 如果耗时过长可以触发告警如发送到Kafka热词mybatisplus整合kafuka记录日志 if (costTime 1000) { // 超过1秒视为慢查询 // kafkaTemplate.send(slow-query-log, logMessage); } } return result; } }4. 谨慎处理“单页500条限制”的突破请求如果有业务方如数据分析团队请求临时调大MaxLimit以导出数据一定要有审批和监控流程。最好提供一个独立的、有权限控制的“数据导出”接口该接口使用独立的、限制更宽松的数据源配置或手动流式查询而不是直接修改核心业务服务的全局配置。配置和使用MyBatisPlus分页插件从“能用”到“用好”关键就在于理解其工作原理并根据实际业务场景进行微调和优化。它就像给你的数据查询引擎加装了一个自动变速箱让高频、重复的分页操作变得平滑顺畅。把今天提到的配置模板、三种用法、问题排查表和优化技巧融入到你的项目中你就能构建出一个既高效又稳健的数据访问层。