抹茶柚子冰先讲个我实际遇到的场景。前两年接了一个老项目，单表数据量也就二十来万，列表页第一页、第二页都挺正常，点着点着突然下一页就空白了，接口也没报错，SQL 看着也执行成功了。排查了半天才发现，问题出在项目里配置的 MyBatis Plus 分页插件上——PaginationInnerInterceptor 里被人设了 maxLimit，请求的每页条数一旦超过这个阈值，插件直接就给你“礼貌地拦下”了。这也是很多人第一次意识到：MyBatis Plus 的分页，从来不是“加个 limit 就完事”那么简单。
这篇文章就是想把 MyBatis Plus 分页这一整块说透，从分页插件的工作原理、基础接入，到 count 优化、深分页治理、Oracle 方言差异、字段名撞关键字这些坑，再到“分页查询慢能用 Redis 优化吗”这类经典问题，最后落到前端 Element UI 分页组件怎么对接。适合刚接触 MyBatis Plus 的后端同学，也适合那些被分页各种“怪现象”折磨过、想系统梳理一遍的开发者。我不打算写得像官方文档那种“罗列配置项”的风格，更多是站在实操角度，把原理和踩坑经验一起讲。
1. 分页插件是怎么把普通查询变成“分页查询”的
1.1 先搞明白：IPage 和分页插件的关系
很多新手会有一个误解：以为 MyBatis Plus 里只要用了 Page 对象，分页就自然生效了。其实不是。
分页这件事拆开看有两部分：
- 一个是“我要第几页、每页多少条”的请求参数，用来承载页码信息，对应
IPage接口和Page实现类。 - 另一个是“真正把 SQL 改写成带
LIMIT的语句”的拦截器，对应MybatisPlusInterceptor里注册的PaginationInnerInterceptor。
Page 只是把“用户想要哪一页”这件事告诉框架，真正动手改写 SQL 的是拦截器。如果项目里只引入了 mybatis-plus 依赖，但没有注册 PaginationInnerInterceptor，那么你调用 selectPage 也不会报错，只是查出来的数据是全量，total 可能还是 0。这种情况我见过不止一次，很多人跑通了一个 Demo，把这套代码粘到老项目里发现分页不生效，第一反应是去检查 SQL，其实问题往往出在配置类上。
所以，理解 MyBatis Plus 分页的第一步，就是记住：分页插件本质是一个 MyBatis 拦截器。它拦截的是 Executor 的 query 方法，在真正执行 SQL 之前，把原始 SQL 改写成“先 count 统计总数，再分页查询当前页数据”两条 SQL。这也是为什么你开启 SQL 日志后，会发现执行一条分页查询时，MyBatis Plus 帮你自动执行了两条 SQL。
1.2 “单页500条限制”从哪来
很多人第一次接触 MyBatis Plus 分页，是在网上搜到“单页 500 条限制”这个说法。这里要澄清一下：
分页插件里有一个安全参数叫 maxLimit，含义是“单页最大条数”。如果请求的 size 超过这个值，插件会做限制处理。不同版本的处理方式略有差异——有的版本是直接把 size 截断成 maxLimit，有的版本是校验不过直接返回空集合。但不管哪种，目的都是防止调用方把 size 传成 10000、50000 这种会把数据库打爆的数值。
关于默认值，这里容易产生误区。MyBatis Plus 不同版本对 maxLimit 的默认处理并不完全一致，有些历史版本默认不限制，有些项目则是团队在配置拦截器时自己设置了 500。所以“500 条限制”更准确的说法是：你所在项目里有个地方把 maxLimit 设成了 500，而你踩到了这个限制。排查方式很简单，全局搜一下 PaginationInnerInterceptor，看构造和 setMaxLimit 的调用即可。
那这个限制要不要去掉？我个人不建议把 maxLimit 调成 -1 或者设成一个很大的值。分页本身就是为了控制单次查询的数据量，如果前端真的需要一次性取几千条，那更应该怀疑是产品设计有问题，而不是分页参数有问题。把限制保留在一个合理值，是对数据库的一道保护。
1.3 分页 SQL 被改写成什么样
分页插件改写 SQL 时，会依据配置的数据库方言不同，生成不同的分页语句。
以 MySQL 为例，原始 SQL 可能是这样的：
sql复制SELECT * FROM user WHERE age > 18
经过分页插件改写后，查询当前页数据的 SQL 大约是这样：
sql复制SELECT * FROM user WHERE age > 18 LIMIT ?,?
第一个参数是 offset，第二个参数是 size。假如当前是第 2 页、每页 20 条，那 offset 就是 20。另外一个 count SQL 大约会变成：
sql复制SELECT COUNT(*) FROM user WHERE age > 18
注意自动生成的 count SQL 会去掉 ORDER BY，因为统计总数时排序没有意义。这个细节看似简单，但在某些老版本或者复杂 SQL 场景下，自动 count 可能不够聪明，后面我会专门讲。
Oracle 方言下，改写后的分页 SQL 会复杂很多。经典的 12c 之前的写法是用 ROWNUM 做两层嵌套，12c 之后可以用 OFFSET ? ROWS FETCH NEXT ? ROWS ONLY。这也是为什么同一个分页代码，换个数据库就可能报错——极大概率是方言没配置对。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 从零配置一套可用的分页查询
2.1 注册拦截器：这一步漏了，selectPage 就像没分页
正确接入方式是在项目里提供一个配置类，把分页拦截器注册到 MyBatis Plus 的拦截器链中。以现在主流的 MyBatis Plus 3.5.x 为例，典型的配置长这样：
java复制@Configuration
public class MybatisPlusConfig {
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor();
// 指定数据库类型，多数据源场景下可以不写，让它自动识别
paginationInterceptor.setDbType(DbType.MYSQL);
// 单页条数限制，按需设置
paginationInterceptor.setMaxLimit(100L);
interceptor.addInnerInterceptor(paginationInterceptor);
return interceptor;
}
}
有几个细节值得说明：
- 为什么要用
MybatisPlusInterceptor而不是老版本的PaginationInterceptor？PaginationInterceptor在 MyBatis Plus 3.4.0 之后已经标记废弃，老项目可以继续用，但新项目建议直接用新写法，后续升级版本少踩坑。 setDbType可以不写，插件会尝试根据数据源连接自动识别。但如果在多数据源或某些连接池代理场景下识别失败，就手动指定，这也是“Oracle 分页报错”最常见的修复手段之一。maxLimit不是必须设置的，不设置的话，插件不会做单页条数限制。我上面那个被 500 限制坑到的项目，就是运维在配置里加了这个值，为了防线上有人把接口当导出工具用。
2.2 单表分页：继承 BaseMapper 就能用
配置好拦截器后，单表分页的代码非常直白。实体类、Mapper 接口都有了之后，Service 层可以这么写：
java复制public IPage<UserVO> pageUsers(int current, int size, String name) {
Page<User> page = new Page<>(current, size);
LambdaQueryWrapper<User> wrapper = Wrappers.<User>lambdaQuery()
.like(StringUtils.hasText(name), User::getName, name)
.orderByDesc(User::getCreateTime);
IPage<User> userPage = userMapper.selectPage(page, wrapper);
// 这里可以再做一次 Entity -> VO 转换，也可以直接用 User
return userPage;
}
关键的 API 点：
new Page<>(current, size)：current从 1 开始，不是从 0 开始，这是和其他很多分页组件不一样的地方，容易写错。selectPage方法接收两个参数：一个是IPage对象，一个是Wrapper查询条件。- 返回的
IPage对象里，除了当前页数据records，还自动填好了total、current、size这几个字段。
很多人在这一层容易忽略的是：selectPage 的第二个参数也可以是 null，表示查询全部，但是分页依然生效。也就是说，分页和查询条件是两个独立维度，哪怕没有条件，也要传一个 Page 对象进去。
2.3 自定义 SQL 分页：复杂查询照样能分
单表查询用自带方法就够了，但实际项目里更多是联表查询、多条件动态 SQL，这时候需要在 Mapper XML 里手写 SQL，同时仍想利用分页插件能力。
做法其实很简单：Mapper 接口方法的第一个参数放一个 IPage，XML 里正常写查询，不需要自己手动拼接 LIMIT，分页插件会帮你处理。举个例子：
java复制public interface OrderMapper {
IPage<OrderVO> selectOrderPage(IPage<?> page, @Param("userId") Long userId);
}
XML 里这么写：
xml复制<select id="selectOrderPage" resultType="com.example.vo.OrderVO">
SELECT o.order_no, o.amount, u.user_name
FROM orders o
LEFT JOIN user u ON o.user_id = u.id
WHERE o.status = 1
<if test="userId != null">
AND o.user_id = #{userId}
</if>
ORDER BY o.create_time DESC
</select>
调用时：
java复制Page<OrderVO> page = new Page<>(current, size);
IPage<OrderVO> result = orderMapper.selectOrderPage(page, userId);
有几个容易踩的点：
- Mapper 方法的第一个参数必须是
IPage，而且不要加@Param注解。如果加了@Param，分页插件会找不到分页参数，导致分页失效。 - XML 里不要自己写
LIMIT或ROWNUM，一旦写了，分页插件改写时可能出现重复分页或者 SQL 语法错误。 - 返回类型可以是
IPage<OrderVO>，也可以是List<OrderVO>。如果用List作为返回值，分页插件依然会执行分页 SQL，但你拿不到total。所以规范的做法是返回IPage，让分页结果完整传给前端。
2.4 返回给前端的统一结构
实际项目里，我不会直接把 IPage 对象作为接口返回值。原因有两个：一是 Page 对象里字段名是 records、total、current、size，有些前端团队约定的字段可能是 list、pageNum、pageSize，直接透出会显得很随意；二是如果后端后续要对分页结果做额外处理（比如打点、包装状态码），统一结构更方便。
我常用的做法是定义一个简单的分页返回对象：
java复制@Data
public class PageResult<T> {
private List<T> list;
private long total;
private long current;
private long size;
private long pages;
public static <T> PageResult<T> of(IPage<T> page) {
PageResult<T> result = new PageResult<>();
result.setList(page.getRecords());
result.setTotal(page.getTotal());
result.setCurrent(page.getCurrent());
result.setSize(page.getSize());
result.setPages(page.getPages());
return result;
}
}
然后在 Controller 里统一返回 PageResult。这样前端不管是对接 Element UI 还是其他组件，字段都清晰可控。
3. 分页性能治理：count 优化、深分页与联表分页
3.1 count 慢：关掉自动 count 还是优化 SQL
分页接口变慢，最常见的瓶颈不是查询当前页数据，而是那条自动生成的 count SQL。
MyBatis Plus 默认会对分页查询执行 count 统计，除非你主动关掉。这个自动 count 在单表简单查询时基本没问题，但遇到多表 JOIN、条件复杂的 SQL，count 可能比数据查询还慢。比如下面的场景：
- 驱动表和被驱动表数据量都很大
- 条件字段没有索引
- JOIN 之后产生大量临时行，而你要的只是在联合结果上数个数
这种情况下，先不谈 SQL 优化，至少要知道几个控制 count 行为的手段：
page.setSearchCount(false)：该次查询不执行 count，total不会被自动填充。如果你的产品形态是“加载更多”而不是传统分页，这一步能省掉不少数据库压力。page.setOptimizeCountSql(false)：关闭 count SQL 自动优化。MP 的自动优化会把ORDER BY去掉，把查询列替换成COUNT(*)，在绝大多数场景是有利的；但有些复杂 SQL 优化后反而不对或者变慢，可以关闭让它原样 count。- 手动写 count SQL：在 Mapper XML 里单独写一个
selectOrderCount，返回Long，在 Service 层手动调，完全绕开自动 count。
从治理角度，我更建议先做两件事：一是给查询条件字段和 JOIN 字段补索引，二是看 count SQL 的执行计划。很多时候 count 慢不是 count 本身慢，而是 WHERE 条件字段没有索引，导致全表扫描。这个问题不解决，关掉自动 count 也只是把问题藏起来，不是真正优化。
3.2 深分页：limit 1000000, 20 的救法
这是个经典问题了。分页插件生成的 SQL 是 LIMIT 1000000, 20，MySQL 在执行时虽然最终只返回 20 行，但它需要先扫描并丢弃前 100 万行，这个成本是实打实的。页码越深，查询越慢，而且越往后越明显。
深分页有几种常见解法，我按实用性排个序：
第一种：改为游标/keyset 分页。 这也是我最推荐的做法。前后端约定：不传 current，而是传 lastId 或 lastCreateTime，SQL 里写成 WHERE id > #{lastId} ORDER BY id ASC LIMIT #{size}。这样每次查询都是基于索引定位，不需要跳过大量行。缺点是失去了“跳到第 N 页”的能力，一般配合“加载更多”按钮或无限滚动的产品形态。
第二种：子查询延迟关联。 如果必须保留传统页码，可以把查询条件先作用到主键上：
sql复制SELECT *
FROM orders o
INNER JOIN (
SELECT id
FROM orders
WHERE status = 1
ORDER BY create_time DESC
LIMIT 1000000, 20
) tmp ON o.id = tmp.id
这样可以减少回表扫描的随机 IO，比直接 LIMIT 1000000 快不少。注意子查询里的 id 和 ORDER BY 字段要能走索引。
第三种：业务上限制页码。 比如管理员后台查询最多允许跳转到第 100 页，超过后提示使用筛选条件。这个方案听起来不够“技术”，但它能直接解决 99% 的深分页问题。与其在数据库层硬扛，不如把产品交互改一改。
3.3 联表查询分页：数据对不对、count 准不准都要管
联表查询分页是 MyBatis Plus 分页里最容易出“灵异现象”的。最常见的翻车场景是：主表和子表是一对多关系，直接 JOIN 后，主表一行被子表多行撑大，分页出来的数据重复，total 也变大了。
举个例子，订单表和订单明细表 JOIN 后，一个订单有 3 条明细，那结果集里这个订单会出现 3 行。这时候按订单维度分页，原本应该每页 10 个订单，实际却可能只显示 4 个不同的订单，剩下的全是重复行。
处理方式通常有两种：
- 先用子查询对主表做分页，再回表补充明细数据。SQL 结构大概是先查订单 ID 分页，再
WHERE order_id IN (...)查明细。 - 在业务层拆分两步查询：第一步查当前页订单 ID，第二步查这些订单的明细，然后在 Service 里组装。这种方法把分页和组装分开，代码反而更清晰。
另外一个容易踩的点是 join 查询的 count 优化。MP 自动生成的 count 可能变成 SELECT COUNT(*) FROM orders o LEFT JOIN user u ON ...，如果 JOIN 之后行数变多，count 结果和实际订单总数对不上。遇到这种情况，要么手动写 count SQL，要么拆分查询。
4. 分页“怪坑”实录：Oracle 方言、关键字冲突与版本兼容
4.1 Oracle 分页的两个典型问题
如果你的项目从 MySQL 迁移到 Oracle，或者本来就用 Oracle，第一个要确认的永远是方言配置。PaginationInnerInterceptor 的 DbType 要设置成 DbType.ORACLE，插件才会生成基于 ROWNUM 的分页 SQL。
Oracle 12c 之前，改写后的 SQL 大致是这种结构：
sql复制SELECT * FROM (
SELECT TMP.*, ROWNUM ROW_ID
FROM (
SELECT * FROM user WHERE age > 18
) TMP
WHERE ROWNUM <= ?
) WHERE ROW_ID > ?
这里有两个常见报错：
ORA-00933: SQL command not properly ended：通常是方言被配成了 MySQL，生成了LIMIT，Oracle 不认。- 分页结果顺序不对：Oracle 的
ROWNUM是在排序前分配的，如果内层 SQL 的ORDER BY没有正确生效，分页结果会乱序。这种情况多半是内层子查询的排序被外层ROWNUM干扰，需要在改写层面保证排序先于ROWNUM分配。
4.2 字段名撞上 SQL 关键字
这个坑不知道有多少人踩过。实体类字段叫 order、desc、group、rank，MyBatis Plus 生成 SQL 时直接用这些字段名，结果执行时数据库报语法错误。
解决方式不复杂，但很多人第一次遇到会懵。
最直接的办法是在实体字段上加注解，把数据库列名显式写成带反引号的：
java复制@TableField("`order`")
private String order;
如果你用的是 PostgreSQL，反引号要换成双引号；Oracle 通常是大写加双引号。这个细节取决于你的数据库方言。
如果你想全局处理，可以在 application.yml 里配置一个全局的列名格式化，比如让 MP 生成 SQL 时统一给字段加反引号。这种全局配置在 MySQL 下有效，但换数据库时反而容易引入新的兼容问题。我更推荐按字段单独处理，命中关键的字段就那么几个，成本极低。
4.3 yml 里到底能不能配分页
最近看到很多人搜“mybatisplus 分页配置文件 yml 里如何配置”，这里统一说清楚：
分页拦截器本身不是一个可以在 yml 里直接通过配置项启用的东西，它必须是一个 Java Bean。你至少需要一个 @Configuration 配置类来注册 PaginationInnerInterceptor。这是 MyBatis Plus 的硬性要求。
那 yml 里能配什么？你可以配置 MyBatis Plus 的全局行为，比如：
yaml复制mybatis-plus:
configuration:
log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
global-config:
db-config:
logic-delete-field: deleted
logic-delete-value: 1
logic-not-delete-value: 0
但这里面没有“分页插件是否开启”的开关，也没有“默认每页多少条”这一项。网上所谓“yml 配置分页”的文章，很多是把“配置 MyBatis Plus 全局属性”和“配置分页拦截器”混为一谈了。新人在项目里找分页配置时，不要只盯着 yml 找，应该先搜代码里的 @Bean 和 MybatisPlusInterceptor。
4.4 版本兼容性：Spring Boot 3 与旧版拦截器
MyBatis Plus 从 3.5.3 开始为 Spring Boot 3 提供了独立的 starter 包，坐标是 mybatis-plus-spring-boot3-starter。如果你用的是 Spring Boot 3，但引的是旧的 mybatis-plus-boot-starter，启动时会遇到一些组件扫描或自动配置不兼容的问题。
另外要注意老项目里的 PaginationInterceptor 和 PaginationInnerInterceptor 不要混用。我在一个项目里见过两个都注册的情况，结果分页 SQL 被改写了两次，查询结果直接翻车。检查方式是把所有 Interceptor 类的引用全列出来，删掉废弃的那个，只保留 MybatisPlusInterceptor 链里的分页拦截器。
5. 分页查询慢，用 Redis 优化时到底该缓存什么
分页慢，很多人的第一反应是加 Redis 缓存。这个思路没问题，但分页缓存的坑比想象中多。如果只是简单地把“接口返回结果”整个塞进 Redis，key 设计不严谨的话，很容易出现数据串页、缓存雪崩、缓存和数据库不一致等问题。
5.1 缓存 key 怎么设计才不串数据
分页数据的缓存 key 至少要包含这几个维度：接口标识、查询条件、页码、每页大小、排序规则。如果查询条件里还有用户维度，key 里还必须带上 userId。
例如：
java复制String cacheKey = "page:order:list:" + md5(queryCondition.toString())
+ ":" + current + ":" + size + ":" + orderBy;
把查询条件做一次 md5，是为了避免 key 过长，同时也能区分不同条件。注意排序规则一定要包含在 key 里，否则用户切了排序方式，命中了另一个排序条件下的缓存，结果就是“数据是对的，但顺序是错乱的”。
5.2 哪些分页能缓存，哪些不能碰
我总结了几条判断标准，大家可以直接套用：
- 热点且变化不频繁的数据，适合缓存。比如配置列表、基础资料下拉、报表看板等，数据变更频率低，缓存命中率高。
- 频繁增删改的数据，不适合直接缓存分页。比如订单列表、流水记录，每时每刻都有新数据进来，缓存失效频率高，而且很容易出现用户刚提交一条数据，刷新列表后没看到的问题。
- 个性化数据（含用户 ID 的查询）缓存成本高，要看这个接口的 QPS 是否值得。如果访问量很高，可以缓存，但要格外小心 key 爆炸。
- 深分页的数据不要缓存。缓存第 3 页和第 300 页的成本一样，但第 300 页的命中率极低，属于典型的“存了等于没存”。这时候应该用前面的深分页优化方案，而不是缓存。
5.3 一个可落地的 Redis 分页缓存封装
假设你确定某个分页接口适合缓存，可以做一个轻量封装。核心思路是：查询时先查缓存，缓存没有再去数据库查，查到后写回缓存并设置一个较短的过期时间。
伪代码逻辑如下：
java复制public PageResult<OrderVO> pageOrdersWithCache(OrderQuery query) {
String cacheKey = buildCacheKey(query);
// 1. 先查缓存
PageResult<OrderVO> cached = redisTemplate.opsForValue().get(cacheKey);
if (cached != null) {
return cached;
}
// 2. 缓存没命中，查数据库
Page<Order> page = new Page<>(query.getCurrent(), query.getSize());
IPage<Order> dbResult = orderMapper.selectPage(page, buildWrapper(query));
PageResult<OrderVO> result = PageResult.of(dbResult);
// 3. 写回缓存，TTL不要设太长
redisTemplate.opsForValue().set(cacheKey, result, 30, TimeUnit.SECONDS);
return result;
}
这里有几个细节要注意：
- 设置一个合理的 TTL，通常 30 秒到 5 分钟，具体看业务对实时性的容忍度。太短缓存没有意义，太长就会出现“数据更新了，列表还是旧的”。
- 可以加一个随机抖动，避免大量缓存同时过期导致数据库被瞬间打满。
- 数据变更时主动删缓存。比如新增、修改、删除操作成功后，把对应的列表缓存 key 删掉，下一请求重新查库回填。主动删缓存比等着 TTL 过期要可靠得多。
- 小心缓存穿透。如果某个查询条件查出来的结果是空的，也要缓存一个空对象，并设置较短 TTL。否则有人反复用同一个不存在的条件请求，每次都穿透到数据库，压力可能比想象中大。
- 更新缓存时不要直接改数据库再改缓存，先更新数据库，再删缓存。这个顺序能有效降低缓存和数据库不一致的概率。
6. 分页结果怎么喂给前端：Element UI 分页组件与远程搜索
分页接口写好了，最终还是要落到前端。热搜里 Element UI 分页组件出现频率很高，我在这块也做一些补充，省得前后端在字段上反复扯皮。
6.1 PageResult 和 el-pagination 的对应关系
前端用 Element UI 的 el-pagination 时，通常需要以下几个字段：当前页码、每页条数、总条数、分页数据列表。
后端 PageResult 如果按我前面定义的结构返回，前端一个大致的对接方式是这样：
html复制<el-pagination
v-model:current-page="query.current"
v-model:page-size="query.size"
:total="pageResult.total"
layout="total, sizes, prev, pager, next, jumper"
@current-change="loadData"
@size-change="handleSizeChange"
/>
query 对象里只需要维护 current 和 size，每次翻页或改变每页条数时重新请求后端，后端返回新的 PageResult。
这里最容易出现的问题有两个：
total是字符串而不是数字，导致组件分页器渲染异常。- 把后端返回的
list和total混在同一层，没有正确解析PageResult。
所以后端在封装 PageResult 时，类型尽量用数值类型，不要用字符串，避免前端还要额外做转换。
6.2 el-select 远程搜索的分页场景
还有一种比较容易被忽略的分页场景：el-select 下拉框选项特别多，比如几千个用户或几千个商品，不可能一次性全查出来。Element UI 的 el-select 支持远程搜索，配合后端的分页接口可以做增量加载。
大致思路是：
- 下拉框触发搜索时，携带用户输入的关键字、当前页码、每页大小请求后端。
- 后端返回当前页的选项列表以及 total。
- 前端在滚动到底部时，把当前页码加 1，继续请求并追加选项。
这种方式比一次性加载几千条数据要稳得多，对数据库和网络都更友好。尤其是当选项数量达到几万时，一次性渲染还会拖垮浏览器，分页或虚拟滚动几乎是必选项。
最后再分享一个操作层面的经验
分页这件事实在是“看起来简单，做起来都是细节”。我给新人的建议是：不要只盯着 LIMIT 那一行 SQL 看。分页产品形态（传统页码还是加载更多）、查询条件的索引覆盖、count 是否必要、缓存是否合理、前后端字段是否对齐，这几件事往往比分页插件本身更影响最终体验。我自己现在接分页需求时，会先问一句“这个列表真的需要跳页吗”，如果是移动端场景，我会倾向改成游标分页；如果是后台管理，再考虑保留页码。先把业务形态定下来，再选技术方案，踩坑会少很多。