MyBatisPlus分页失效与500条限制：从原理到实战的完整排查指南

1. 项目概述：MyBatisPlus，一把梭还是深水区？

如果你做Java后端开发，近两年几乎绕不开MyBatisPlus这个名字。它不是一个全新的ORM框架，而是站在MyBatis的肩膀上，把日常CRUD、分页、条件构造、逻辑删除这些高频操作封装成开箱即用的API，让开发者从繁琐的XML映射和重复的SQL编写里解放出来。网上说“有了MyBatisPlus，单表操作不用写SQL”，这句话基本属实，但真正把它用到生产环境，会发现远不止“开箱即用”这么简单——分页失效、500条限制、多租户插件冲突、乐观锁失效，这些坑我都踩过，而且每一个都是线上事故级别的教训。

这篇内容不是官方文档的复读机，而是结合我自己的项目经验，把MyBatisPlus从集成、设计、分页、防坑到性能调优的完整链路梳理一遍。适合正在使用或准备使用MyBatisPlus的Java开发，尤其是那些项目里已经有现成MyBatis框架、想平滑迁移的团队。不管你是刚接触这个框架的新手，还是已经写了半年但被各种“奇怪现象”困扰的老人，这篇文章都能提供一些在搜索引擎里很难一次性凑齐的实战结论。

先说清楚一个前提：MyBatisPlus不是MyBatis的替代品，它是增强插件。底层SQL执行还是MyBatis那套机制，只是帮你把大量机械式的单表操作自动化了。这个定位决定了一件事——凡是“自动生成”的能力，都有它的边界和默认行为，不理解这些边界，迟早会翻车。

2. 核心功能拆解：哪些能力真正值得依赖？

2.1 BaseMapper：单表CRUD的最短路径

任何一个继承BaseMapper的接口，立刻获得insert、deleteById、updateById、selectById、selectList等十几个方法。这对业务开发来说，减少的代码量是肉眼可见的。比如一个用户表，传统MyBatis要写UserMapper.xml，配resultMap、写SQL、管理参数，现在一个接口加一个实体类注解就搞定。

在多数业务系统里，单表CRUD能占数据访问层的六到七成工作量。BaseMapper把这部分压缩到接近零。但这里有个容易被忽视的细节：updateById默认只更新非null字段。也就是说，如果你把一个实体的某个字段手动置为null，调用updateById时这个字段不会被更新到数据库。这在大多数场景下是合理的“部分更新”语义，但如果你确实想“将某个字段置空”，就会被这个默认行为坑到。解决方案是使用UpdateWrapper显式调用.set("field", null)，或者专门写一个update方法。这个坑我在数据修正脚本里遇到过，当时以为数据没更新，查了半天才发现是null字段被自动忽略了。

2.2 条件构造器：Wrapper才是灵魂

BaseMapper提供的方法只覆盖了最简单的查询，真正的灵活性来自QueryWrapper和LambdaQueryWrapper。前者用字符串列名，后者用Lambda方法引用，编译期就能校验列名是否存在。我个人强烈建议直接上LambdaQueryWrapper，因为字符串拼写错误是运行时才能发现的，而Lambda写错直接编译报错。团队协作时，代码重构字段名，Lambda版本也能自动同步，不会留下隐性Bug。

条件构造器支持eq、ne、gt、ge、lt、le、between、like、in、isNull、orderByDesc等一系列方法，覆盖了90%以上的单表动态查询场景。比如筛选状态为激活且创建时间在最近七天的用户，一个链式调用就搞定：

List<User> users = userMapper.selectList( new LambdaQueryWrapper<User>() .eq(User::getStatus, 1) .ge(User::getCreateTime, DateUtil.offsetDay(new Date(), -7)) );

用Wrapper不用XML的好处很明显：动态SQL的拼接逻辑在Java层就能看清，不需要跳转到XML文件里数<if>标签。但也正因为如此，复杂SQL（多表Join、子查询、union）依然建议走XML，不要让Wrapper强行承担它不该承担的重任。

2.3 AR模式、逻辑删除与乐观锁：三个高频插件的取舍

ActiveRecord模式允许实体直接调用insert()、updateById()、selectById()，不需要注入Mapper。这个模式在小型项目和快速原型里很爽，但到了中大型项目，我基本不推荐——它让数据访问逻辑散落在实体里，和分层架构的边界有点冲突。团队一旦约定“所有数据库操作走Mapper层”，AR模式就是个异类。

逻辑删除是MyBatisPlus最受欢迎的能力之一。实体字段上加@TableLogic，配置全局逻辑删除值，之后所有selectList自动追加WHERE deleted = 0，deleteById自动变成UPDATE SET deleted = 1。这个机制极大降低了物理删除带来的数据不可恢复风险。但注意，它有个隐蔽的坑：如果业务里有selectCount统计、或者基于唯一索引的插入，逻辑删除会导致重复数据问题。比如用户表有唯一索引uk_phone，逻辑删除后，同一个手机号再注册就会因为“已存在一条deleted=1的记录”而报错。这时候要么把唯一索引改成复合索引（phone + deleted），要么在业务里先物理清理，需要额外的方案设计。

乐观锁插件实现的思路是：执行update时自动带上version = currentVersion条件，更新成功后version + 1。配置方法很简单，在实体字段上加@Version，再注册一个乐观锁插件Bean。但实际使用时我建议配合重试机制，否则并发高的场景下，后提交的请求直接update 0行，前端拿到的提示是“操作失败”，体验并不好。我通常是在Service层捕获update == 0的情况，自动重试一次新的查询和更新，或者直接告诉用户“数据已被他人修改，请刷新后重试”。

3. 工具选型与项目集成：为什么建议升级到新版本？

3.1 Spring Boot集成：三行代码跑起来

MyBatisPlus和Spring Boot的集成非常顺滑。引入mybatis-plus-boot-starter，配置数据源，启动类加@MapperScan，然后写一个继承BaseMapper的接口，就完事了。我在实际项目中，从零搭建一个带分页查询和逻辑删除的模块，大概十分钟就能跑通。对比传统MyBatis + PageHelper + XML的搭建流程，省掉的配置量是实打实的。

这里要提醒一个版本问题：如果你是老项目从MyBatis迁移到MyBatisPlus，除了替换starter，还要检查mybatis.mapper-locations配置是否还在。MyBatisPlus兼容原来的XML配置路径，但需要在application.yml里显式维护，否则原本写在XML里的自定义SQL会全部失效。

3.2 版本差异：别停在3.4.X的旧习惯里

MyBatisPlus的版本迭代相当快，3.4到3.5之间的行为差异不小。比如3.5.x对分页插件的内部实现做了重构，对多租户插件的执行顺序也有了更严格的约束。我在早期项目里用的是3.4.2，后来升级到3.5.3时，发现原本正常工作的一条复杂分页SQL报错，排查后发现是分页插件和多租户插件在Count SQL生成时的顺序问题。后来通过显式配置插件执行顺序解决了。

所以我的观点是：新项目直接上3.5.x最新稳定版，老项目升级前先看官方升级文档，尤其关注插件、分页、逻辑删除这几个模块的兼容性说明。网上很多教程还停留在3.4时代，代码照抄可能跑得起来，但隐藏的行为差异不是文档里一眼能看出来的。

4. 分页机制深入解析：为什么“单页500条限制”和“分页失效”总是同时出现？

4.1 分页插件的工作原理

MyBatisPlus分页插件不是简单地在SQL末尾加LIMIT，而是通过拦截器机制，在执行前重写SQL：

• 自动生成Count SQL，用于计算总记录数。
• 生成带有LIMIT offset, size的查询SQL。
• 组装成Page对象返回，包含records、total、current、size等字段。

具体配置如下：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); PaginationInnerInterceptor pagination = new PaginationInnerInterceptor(DbType.MYSQL); pagination.setMaxLimit(500L); interceptor.addInnerInterceptor(pagination); return interceptor; } }

看到没有，很多人在网上搜到类似setMaxLimit(500L)的配置，其实是防止一次性查询太多数据导致数据库压力暴涨。但如果你业务上确实需要一次拿超过500条（比如导出功能），就会报“单页500条限制”错误。这个限制是分页插件默认附加的，不是框架本身的设计缺陷。我项目里就遇到过运营后台导出用户数据，直接调selectPage传了个超大size，结果被框架拦了。后来针对导出接口单独放开了限制，或者在查询时用流式处理，而不是一味加大size。

4.2 分页失效的几种典型场景

“分页失效”是搜索热词，也是我排查最多的问题之一。总结下来最常见的有四种：

1. 自定义SQL拼接了分页条件：XML写了LIMIT，同时又启用分页插件，双重分页会导致结果错乱。
2. 插件未注册或顺序不对：Spring Boot项目里漏了MybatisPlusInterceptor配置，分页自然不起作用。
3. 多租户插件和分页插件顺序颠倒：如果多租户插件在分页插件之前执行，生成的Count SQL可能没有带上租户隔离条件，统计总数会不准。
4. SQL中含有GROUP BY或DISTINCT：分页插件自动生成的Count SQL可能不是简单SELECT COUNT(*)，需要用子查询包一层，但某些情况下插件无法正确改写，导致总数不准。

典型场景是联表查询加DISTINCT后再分页，插件重写SQL时会把DISTINCT丢掉或者生成错误的Count语句。我当时的解决方案是在XML里手动写分页，或者在实体查询里先查出主键ID再分页，效率其实更高。

4.3 如何判断是“数据库限制”还是“框架限制”

网上不少讨论把单页500条限制和数据库性能画等号，实际上setMaxLimit(500L)只是框架层的一个安全阈值，跟数据库无关。MySQL的LIMIT理论上能接受很大的值，但大偏移量的LIMIT 100000, 100性能极差，因为需要扫描前十万行再丢弃。所以真正合理的分页策略是：

• 用户操作用分页，每页20到100条。
• 批量导出走后台异步任务，用游标或分段查询，一次取5000条也可能没问题，但不要通过分页插件硬传大size。
• 如果确实要“下一页”，无论前台后台，都应该用WHERE id > lastMaxId ORDER BY id LIMIT size这种键集分页（keyset pagination），而不是LIMIT offset。MyBatisPlus 3.5.x支持在LambdaQueryWrapper里加.gt(User::getId, lastId).last("LIMIT 100")来实现，效率提升非常明显。

提示：如果你看到“单页500条限制”报错，先检查PaginationInnerInterceptor的setMaxLimit，再检查业务代码里是否传入了异常大的size。如果完全没配置setMaxLimit，那多半是当前版本有全局默认值，官方文档里写得很清楚。

5. 实操过程：从零配置一个带分页和逻辑删除的用户模块

5.1 表结构与实体设计

假设要做一个用户管理模块，表结构如下：

CREATE TABLE `user` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `name` varchar(50) NOT NULL, `phone` varchar(20) DEFAULT NULL, `status` tinyint(4) DEFAULT '1', `version` int(11) DEFAULT '0', `deleted` tinyint(4) DEFAULT '0', `create_time` datetime DEFAULT NULL, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

实体类：

@Data @TableName("user") public class User { @TableId(type = IdType.AUTO) private Long id; private String name; private String phone; private Integer status; @Version private Integer version; @TableLogic private Integer deleted; private LocalDateTime createTime; }

注意@TableName用于指定表名，@TableId指定主键策略。这里用自增主键，比较简单；分布式场景下可以用ASSIGN_ID（雪花算法），但要注意数据库字段类型和Java Long类型的匹配。

5.2 Mapper与Service分层

public interface UserMapper extends BaseMapper<User> { }

Service层如果只想做很薄的封装，可以直接继承ServiceImpl：

@Service public class UserService extends ServiceImpl<UserMapper, User> { public Page<User> queryPage(int page, int size, String keyword) { LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>(); wrapper.like(StringUtils.isNotBlank(keyword), User::getName, keyword) .orderByDesc(User::getCreateTime); return this.page(new Page<>(page, size), wrapper); } }

ServiceImpl里已经铺好了page、save、updateById等常用方法，业务里直接调，比自己在Service里转发Mapper方法省事很多。这里我推荐一个习惯：Controller只接参数，调Service拿到Page对象后转成VO返回，不要直接把实体丢给前端，尤其注意把deleted、version这类内部字段屏蔽掉。

5.3 完整分页查询代码示例

Controller层：

@RestController @RequestMapping("/user") public class UserController { @Resource private UserService userService; @GetMapping("/page") public Result<Page<UserVO>> page(@RequestParam int page, @RequestParam int size, String keyword) { Page<User> userPage = userService.queryPage(page, Math.min(size, 100), keyword); // 转VO、封装Result return Result.ok(convertPage(userPage)); } }

我特意写了Math.min(size, 100)，防止前端恶意传一个10000的size。后端接口永远不要信任前端参数，这是基本的安全意识，同时也是对分页插件maxLimit的补充保护。

5.4 分页插件参数配置要点

• maxLimit：建议生产环境设置成200到500，防止全表扫描。
• overflow（是否处理超出页数）：默认false，如果请求的page数超过总页数，返回空列表，这个比较合理。设置为true时，插件会自动把current修正为最后一页，所以要看业务是否需要这种“自动纠偏”行为。
• dbType：必须正确配置，不同数据库（MySQL、PostgreSQL、Oracle）的分页方言不一样，配错了会在运行时生成错误的SQL。

我在内网环境搭过一个PostgreSQL的测试库，当时忘了改dbType，结果分页SQL里生成了MySQL的LIMIT写法，直接报语法错误。这类问题隐蔽就隐蔽在，单测如果没覆盖分页查询，根本发现不了。

6. 常见问题与排查技巧实录

6.1 问题速查表

6.2 排查分页失效的三种工具

分页失效往往不是“配置错了”这么简单，尤其在老项目改造时。我遇到的场景是：原有MyBatis项目里已经配置过PageHelper，后来引入MyBatisPlus时没有移除，两个分页拦截器同时生效，导致SQL被改了两次、结果错乱。这时候最有效的排查手段是：

1. 开启MyBatis SQL日志，看最终打印出来的SQL语句是什么样的。如果出现了两个LIMIT，基本可以确定拦截器冲突。
2. 检查应用启动时的Bean加载日志，确认MybatisPlusInterceptor是否被正确实例化。
3. 查看Count SQL生成是否正确——很多分页失效指的不是“SQL报错”，而是总数不对，这时要留意插件生成Count SQL的日志。

6.3 我踩过的版本坑

早年在3.5.2版本上，我遇到过分页插件在InnerInterceptor链上执行顺序混乱的问题。当时项目同时用了多租户、数据权限、分页三个插件，结果某个SQL的总数少了一半。最后在MyBatisPlus官方GitHub的issue里翻到同款问题，确认是插件顺序导致TenantLineInnerInterceptor先执行了Where拼接，随后分页插件生成Count SQL时没保留租户条件。解决办法是在配置类里调整addInnerInterceptor的顺序：

interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(tenantLineHandler)); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));

租户插件必须在分页插件之前执行，DataPermissionInterceptor则根据业务需要放在更前或更后的位置。这个顺序不是一个玄学，而是有明确逻辑的——先做行级数据过滤，再做分页统计，才不会出现“总数里包含了不该看到的数据”。

6.4 针对“单页500条限制”的三种解决策略

分页插件默认情况下，如果没有显式设置maxLimit，其实不会限制。你在网上看到“MyBatisPlus单页500条限制”的说法，通常来自两个渠道：一是官方文档示例中设置了setMaxLimit(500L)，二是某些团队在代码里抄了这个配置后产生了一个“不成文限制”。如果你的项目确实有这个配置，且业务需要突破，有三种处理法：

• 简单粗暴：调大或移除setMaxLimit，适合内部管理系统、并发量不高的场景。
• 导出场景单独处理：写一个异步导出任务，用stream流或分段查询，而不是期望分页插件支持一次返回几万条。
• 键集分页：如果你追求性能和数据一致性，别依赖Page的current/size，用WHERE id > ? ORDER BY id LIMIT ?，分页插件一样支持，只是换一种写法。

注意：分页插件保护的是查询内存和数据库扫描量，而不是“限制你的业务”。如果你发现自己经常需要查超过500条，问题的根源往往不是框架，而是业务设计上缺了一个批量任务或异步导出的出口。

7. 从MyBatis平滑迁移到MyBatisPlus：三个迁移决策点

7.1 单表操作直接替换，XML里的复杂查询保留

迁移的第一步是明确边界。BaseMapper能解决的直接替换，Wrapper能写的动态条件也尽量从XML里抽出来。但多表Join、复杂子查询、动态排序字段、跨表更新这些操作，不要硬搬进Wrapper，继续留在XML里。MyBatisPlus并不禁止你在Mapper接口里定义List<User> selectComplexList(@Param("param") XxxParam param)，再配对应的XML片段。它只是多给了你一条快车道，而不是逼你丢掉原有的人行横道。

我见过一个项目为了“全面拥抱MyBatisPlus”，把一条能跑30秒的复杂报表SQL硬拆成三个BaseMapper查询然后内存拼接，结果性能还不如原来一条SQL快。迁移的意义是消除无聊代码，不是消灭SQL。

7.2 处理分页插件冲突

如果原项目用了PageHelper，迁移时一定要移除PageHelper依赖和拦截器配置，只保留MyBatisPlus的MybatisPlusInterceptor。兄弟姐妹插件共存的事故，我见过不止一次——两个插件都会尝试修改SQL，最后生成的SQL里出现了两个LIMIT，或者Count SQL被重复包装。

7.3 统一实体和字段映射规则

老项目里数据库字段一般是user_name这种下划线风格，实体用userName驼峰风格。MyBatisPlus默认开启了驼峰映射，不需要额外配置。但如果有历史字段名不满足这个规则，要么在实体字段上加@TableField("xx_yy")，要么统一改数据库字段命名。混合使用时排查成本会直线上升，最好保持一致的约束。

8. 性能优化与扩展：当MyBatisPlus不再“够用”时

8.1 大批量插入的最优解

ServiceImpl里的saveBatch底层是分段执行INSERT，默认每1000条做一次批量插入。如果你的数据量到了几十万条，这个方法还勉强可用，但上百万条时就不建议用saveBatch硬插了。我实测过，百万级数据用saveBatch的时间是分批手动PreparedStatement批量插入的三到四倍。追求性能时，用JdbcTemplate或原生JDBC Batch直接干，MyBatisPlus在这类场景并不擅长。

8.2 分页查询慢的终极解法：键集分页

传统LIMIT 100000, 20这种深分页，数据库要扫描前十万行，再丢掉。数据量上千万元素后，这个延迟会膨胀到用户无法忍受。键集分页是把“第几页”换成“上一页最后一条记录的ID或时间”，让数据库直接从那个点开始扫描。MyBatisPlus的Wrapper虽然不支持直接标记“键集”，但你可以用.last("LIMIT 20")配合where id > ?实现。前端传参不再是page，而是lastId，这个改动对接口调用方是透明的，但性能提升是数量级的。

我在一个流水表查询场景里验证过：三千万条数据，偏移量到二十万时，传统分页耗时约1.8秒，换成键集分页后稳定在150毫秒以内。这才是分页真正的性能优化方向，而不是调整maxLimit。

8.3 SQL日志与性能监控

开启mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl可以看到完整SQL和参数，开发阶段很有用。上线前记得关掉，或者用Slf4jImpl输出到日志文件并按级别过滤。我一般还会结合阿里的druid连接池或p6spy来记录慢SQL，但注意p6spy有性能损耗，生产环境中不一定能接受，要按需取舍。

9. 一个真实的线上事故复盘

这里分享一个我亲自处理的库存扣减事故。某促销活动接口，用户下单时调用updateById更新库存字段，导致库存被“负卖”。排查后发现代码用UserService.getById(productId)读取库存，在内存中减1，再调用updateById写回。高并发下两个线程同时读到库存=10，各自减成9，再写回，最终库存变成9，但实际卖了两单。这是典型的读改写竞态问题，不是MyBatisPlus的Bug，而是使用方式错了。

修复方案有两个方向：

• 使用乐观锁@Version，让更新时检查版本号，冲突后重试。
• 更简单的是直接在SQL层做原子更新：UPDATE product SET stock = stock - 1 WHERE id = ? AND stock > 0，返回影响行数判断是否扣减成功。

MyBatisPlus的Wrapper可以这样写：

LambdaUpdateWrapper<Product> wrapper = new LambdaUpdateWrapper<>(); wrapper.eq(Product::getId, productId) .gt(Product::getStock, 0) .setSql("stock = stock - 1"); int rows = productMapper.update(null, wrapper);

这个场景是框架最容易让人掉坑的地方——因为updateById太方便了，大家下意识地忘了它只是“数据覆盖写回”，不是“并发安全操作”。类似的问题还有金额转账、优惠券扣减，凡是涉及“先读后写”的，都要警惕竞态条件。

10. 一些常规文档找不到的实用细节

• Page对象序列化：Page类继承了分页参数，直接返回给前端会带上很多无意义字段。建议封装成自己的PageVO，只保留records、total、current、size。
• 逻辑删除字段不要参与唯一索引：前面提到过，再强调一次，线上唯一索引冲突事故里，逻辑删除是高频元凶。
• 实体字段默认值：Java侧定义字段时不要给默认值，比如private Integer deleted = 0，在某些情况下会导致MP生成SQL时误判你有没有显式设置字段。让数据库来维护默认值，实体只做显式的状态变更。
• 时间字段：推荐统一用LocalDateTime，MP在3.5.x已经能很好地在MySQL和Java类型之间映射。老项目里的java.util.Date建议逐步替换，长期维护会省心很多。
• ID策略选择：数据量万级以下自增主键没问题；分布式多节点插入时，用ASSIGN_ID（雪花算法）避免主键冲突；但雪花ID是长整型，前端JS中Long精度会丢失，所以返回给前端时要转字符串。

按照我的习惯，每当引入一个新框架，第一件事是确认它的默认行为和边界条件，再把边界条件的验证用例写进单元测试。MyBatisPlus也一样：updateById忽略null是默认行为，那就要有测试用例证明这个行为符合预期；maxLimit是默认保护，那就得有测试用例防止后人误改。底层的框架只是一种工具，真正让项目长期稳定的是提前定义好的规则和测试网。对于MyBatisPlus，我最后想说的是，它的价值不在“不需要写SQL”这种极简主义叙事里，而在于把那些重复的、容易出错的、和人相关的琐碎操作收敛到一个统一机制中，让开发者把真正的精力留给业务逻辑和代码质量。用好它的最好方式，不是什么都依赖它，而是知道它哪些能力可靠、哪些边界需要自己守护。