1. 先搞清楚PageIndex的出身：0基还是1基，这是所有混乱的源头

做过后端接口对接的朋友应该都体会过，前后端联调分页功能时最诡异的一类Bug就是：第一页正常，第二页的数据和第二页重复，或者第二页莫名其妙少了一条。排查到最后，十有八九是PageIndex的基数约定不一致。

我最早被这个坑压到，是在一次给管理后台做列表接口时。前端用的组件库分页器默认从1开始计数，而后端用的分页框架Pageable默认从0开始。前端把currentPage=2传给后端，后端解析成offset=2*10=20，直接跳过了第10到第19条数据，页面看起来就是“漏了一屏”。这种问题不在报错时暴露，只在数据对不上时暴露，非常阴。

不同技术栈对PageIndex的起点定义差异很大。我整理了一个表，大家对接前先对照一下：

这个表的意思不是说谁对谁错，而是说PageIndex本身就是一个约定俗成的概念，跨语言、跨框架时会悄然改变语义。最保险的做法，是后端接口文档里明确写出“pageIndex从1开始”或“page从0开始”，并且用参数校验挡掉非法值。不要指望前端能记住后端框架的默认值。

另外一个容易混淆的细节是pageSize的边界。很多后端框架允许pageSize传很大，甚至传10000，直接把数据库压垮。我在接口层面通常会对pageSize做clamp处理，比如最大只能取100，超过就报参数错误或静默截断。这种防御看起来“多此一举”，但线上环境被扫到一个超大pageSize确实会拖垮数据库，这类事故不少见。

还有一个隐藏点：PageIndex和总页数的关系。后端计算总页数时，常用公式是totalPage = Math.ceil(total / pageSize)。前端根据这个值来决定是否显示“下一页”按钮。如果前端自己用total / pageSize然后向下取整来算，就会出现总页数差一页的情况，最后一页永远点不进去，或者点进去是空的。前后端对总页数计算口径不一致，也是PageIndex相关的经典联调事故。

提示：规范的返回体里一定要同时返回total、totalPage、pageIndex、pageSize这四件套，不要只返回total。前端拿到这四个字段后，不需要自己推总页数，直接渲染即可，能从根上避免口径不一致的问题。

2. 前端组件里的PageIndex：拿到的是页码，不是下标

前端工程师每天都要跟分页组件打交道，但很多人没意识到，组件的change事件里回调的那个参数，究竟是页码还是索引，是极容易搞混的。以Element Plus的el-pagination为例，current-change事件的回调参数是当前的current-page，这个值的起点是1，也就是用户眼里的“第1页”。但如果你在请求后端时分页接口正好是0基的，就必须手动做currentPage - 1的换算。

这个换算逻辑看似简单，真正写起来却有很多细节。比如搜索条件变化后，原本在第5页，搜索结果只有2页，此时如果不把pageIndex重置为默认第一页，请求发出的页码就落在空数据上，页面上显示一片空白，用户以为搜索失败了。正确做法是：搜索按钮点击时，先把pageIndex重置为初始值（通常是1），再发起请求。

另外一类很常见的问题是“删除末页最后一条数据”。假设当前在第5页，每页10条，恰好这一页只有1条数据，删除之后这一页就空了。如果不重新计算总页数并将pageIndex回退到新的最后一页，用户停留在第5页看到的就是个空表，同时“删除成功”的提示也已经弹出，体验非常割裂。

前端还有一个隐性场景：表格的滚动加载（无限滚动）模式下，PageIndex概念会变成“已加载页数”。这类模式我习惯用一个自增的counter来实现，每次滚动到底部时先判断是否还有下一页，再让counter自增。但要注意：如果此时用户切换了筛选条件，counter必须重置为1，同时清空已有列表数据。否则新旧条件的数据会混合在同一份列表里，看起来就是数据错乱。这个问题在真实项目中几乎每周都能遇到——很多人忘了重置counter，导致切换筛选后列表里混着上一次条件的数据。

无限滚动还有一个坑：已加载完全部数据后，下拉刷新会重复请求同一页。前端需要用一个hasMore标志来终止后续请求，并且在请求结束前加锁，防止重复触发。我见过几个项目在这个问题上翻车，最后的解决方案都是在请求层加了一个简单的isLoading状态拦截，避免并发请求同一页。

注意：凡是涉及PageIndex的异步请求，都应考虑“竞态条件”。用户快速翻页或快速切换条件时，先发出的请求可能后返回，后发出的请求反而先返回，导致最终显示的数据和当前页码对不上。解决方案很简单：在请求层记录最后一次发出的请求序号，响应返回时只处理最新那个序号。这个习惯能省很多时间。

3. 后端分页接口的参数校验与返回设计

写后端分页接口时，大部分人会把注意力放在SQL怎么写，却很少认真设计参数校验和返回结构。但实际上，PageIndex的参数校验才是决定这个接口“抗不抗造”的关键。

我通常会在Controller入口做如下校验：

@GetMapping("/list") public Result<PageResult<ItemVO>> list( @RequestParam(defaultValue = "1") Integer pageIndex, @RequestParam(defaultValue = "10") Integer pageSize) { // 页码最小为1，pageSize限制在1~100之间 if (pageIndex == null || pageIndex < 1) { pageIndex = 1; } if (pageSize == null || pageSize < 1) { pageSize = 10; } pageSize = Math.min(pageSize, 100); // 计算offset int offset = (pageIndex - 1) * pageSize; // ... }

这里有几个原则：

• 不要因为PageIndex不合法就抛异常。分页请求来自前端或客户端，参数不合法时更友好的响应是返回空列表，而不是一个500错误。
• 对pageIndex做下界截断（小于1时重置为1），但不做上界截断。总页数是变动的，直接限制pageIndex不超过totalPage反而会引入脏数据问题，不如让SQL自己返回空集。
• pageSize一定要有上限。100是个比较稳妥的默认值，超过上限的请求要么截断，要么拒绝。

返回体设计方面，我推荐用一个统一的分页包装类：

{ "code": 0, "message": "ok", "data": { "list": [], "total": 1024, "totalPage": 103, "pageIndex": 1, "pageSize": 10 } }

totalPage由后端统一计算，前端不要自行推导。这样前端组件可以直接用totalPage控制分页器的最大页码，避免每一端各自算，算出来的结果不一致。

另外，查询总数和查询列表是两条独立的SQL，这两条SQL必须放在同一个事务边界内吗？其实不一定。对绝大多数业务来说，数据量在百万级以内，count和list之间的时间差造成的新增或删除，对用户来说是无感的。如果你强行加事务，反而可能因为长事务影响到写入性能。我一般的做法是：count查询走从库，list查询也走从库，主从延迟稍大时允许轻微的数据不一致，换来的是主库的写入压力大幅下降。

提示：如果list查询结果为空但total大于0，这通常是页码越界的标志。此时可以直接把pageIndex修正为totalPage并重查一次，这个重试逻辑放在后端接口内部，前端完全无感。它能有效避免“第100页只剩一条数据，删掉后页面空白”的问题。

4. 从PageIndex到深分页：页码变大之后的性能拐点

PageIndex本身只是一个数字，真正让人头疼的是这个数字变大以后。

用一个最简单的例子说明：LIMIT 1000000, 10。MySQL执行这段SQL时，不是直接从第100万条开始读10条，而是先把前100万条全部扫描一遍并丢掉，然后才返回第100万条之后的10条。这意味着你翻得越深，数据库做无用功越多，响应时间呈线性甚至超线性增长。到了几百万页的深渊，一个普通的列表接口就能把数据库连接池打满。

我先解释一下为什么MySQL会这么笨。原因是MyISAM和InnoDB的行存储并不是按你查询的排序顺序物理排列的，数据库必须通过索引扫描来定位“第N行”。如果走的是主键索引，它确实可以快速跳到某个主键值附近，但LIMIT OFFSET不能直接转换成主键位置，只能老老实实从第一条开始数。所以offset越大，扫描量就越大，这是结构性的劣势，无法通过加索引根治。

解决深分页有两条主流路径：

路径一：延迟关联，也叫子查询分页。SQL改成：

SELECT * FROM orders WHERE id >= ( SELECT id FROM orders ORDER BY id LIMIT 1000000, 1 ) ORDER BY id LIMIT 10;

内层子查询虽然也要扫100万行去找起点ID，但因为它只返回一个主键值，不需要回表拿完整行数据，所以整体IO量比直接LIMIT OFFSET小很多——这种优化方式在许多场景下能让耗时从数秒降到几十毫秒以内。

路径二：书签（keyset）分页，也叫“关建键值定位”。核心思路是放弃PageIndex，改成“查下一页时带上上一页最后一条数据的排序字段值”：

SELECT * FROM orders WHERE create_time < '2025-06-01 12:00:00' ORDER BY create_time DESC LIMIT 10;

这种写法天然规避了OFFSET扫描问题，因为数据库可以直接用复合索引定位到create_time的指定位置，速度与页码无关。代价是：用户无法直接跳转到第500页，只能一页一页往下翻。

我把这两种方案的取舍总结一下：

5. 从PageIndex到游标：什么时候应该换分页方案

书签分页方案落地时，接口的入参就不应该再叫PageIndex了，而应该叫cursor或者nextToken。这是一个根本性的API设计变化：从“第几页”变成“从哪条开始”。

我建议改造的时机是：

• 数据量达到百万级，且用户日常操作多为“往下翻”时
• 列表顺序按时间倒序排列，而不是允许用户按任意字段排序时
• 对实时性有要求，不希望翻页过程中插入新数据导致重复或漏读时

游标分页的典型接口结构如下：

{ "data": { "list": [ { "id": 1024, "title": "hello", "createTime": "..." } ], "nextCursor": "1024", "hasMore": true } }

客户端每次请求带上前一次响应中的nextCursor，服务端用这个值定位起点：

SELECT * FROM articles WHERE id < #{nextCursor} ORDER BY id DESC LIMIT #{pageSize};

由于id是主键，这个查询几乎可以恒定地在几毫秒内返回，无论前面已经翻了多少页。这种体验在用户刷信息流时是碾压式的。

但游标分页也不是银弹。它最大的问题是：无法跳页。产品经理如果说“用户要能直接点第38页”，那游标方案就直接出局。其次是排序不灵活，只支持单一稳定排序字段（通常是主键或时间戳），如果列表允许用户按价格、热度等多种字段排序，用游标就会很别扭，因为每个排序字段都要设计对应的游标编码。

所以我的设计原则是：管理端、分页跳转需求明确时继续用PageIndex；C端信息流、时间线类列表优先考虑游标。两种不是替代关系，而是定位互补。老项目不要贸然把PageIndex全改成cursor，可以先从高频访问的接口试点，观察性能和用户反馈后再铺开。

经验分享：如果短期内不想引入游标，但又要缓解深分页问题，可以先做“分页上限控制”——后端限制PageIndex最大只能到100页或200页，超过后返回空列表并在响应里加一个提示字段。对于绝大多数用户来说，他们根本不会翻到第100页以后，这个限制几乎不影响正常使用，却能有效阻止恶意爬虫深翻你的页面。

6. 实战排错复盘：三个PageIndex相关的典型事故

6.1 第一页和最后一页数据重复

现象：后台列表第一页最后一条数据和第二页第一条数据重复，或者相反地漏了一条。数据量小时看不出来，数据量大了就露馅。

排查链路：

• 先确认SQL里LIMIT的offset是不是算错了。
• 果然，后端用的分页框架是0基，前端传的是1基，中间少了一次减1。
• 修复方式：在Controller统一做pageIndex - 1的换算，禁止在业务层再算一次，避免每个接口各自换算导致每次都不一样。

这个案例最典型，但也很容易在大型项目中反复出现——每个接口的入参命名不统一，有的叫page，有的叫pageIndex，有的叫currentPage，有的直接用offset。出现重复数据的根因是“两层换算”，所以后来我定了个死规矩：前端传的页码统一叫pageIndex且从1开始，后端At层统一换算为offset，业务层只认offset，任何地方不许再出现“页码减一”的操作。

6.2 搜索条件变化后页面停留在深层

现象：用户在第10页搜索新关键词，结果集只有2页，前端把请求发出去了，后端返回空数据。页面白屏，用户以为系统坏了。

排查链路：

• 看请求参数，pageIndex确实还带着10。
• 看后端返回，list是空的，totalPage只有2。
• 问题是前端没有在搜索时重置pageIndex。

修复方式：写一个统一的search方法，先setPageIndex(1)，再fetchList()。另外后端做了越界修正逻辑（前面提到的totalPage重查），双保险。

排查这类问题有一个快速技巧：把Network面板的请求参数和后端返回的totalPage、pageIndex字段对照起来看。一旦发现请求的pageIndex远远大于totalPage，前端重置逻辑一定有缺陷。

6.3 导出功能把所有分页参数全忽略

现象：列表分页正常，但点“导出全部”时，后端只导出了第一页的10条。

排查链路：

• 导出接口没有复用列表接口，而是自己写了一条无分页的SQL。
• 但导出代码里复制了列表服务的部分逻辑，分析师在拼SQL时把LIMIT条件也带上了。
• 因为导出时不传pageIndex参数，导致前端传来的pageIndex为null，MyBatis动态SQL里LIMIT 10直接生效。

修复方式：导出接口的Service方法单独提供，不传任何分页参数，用独立的一条查询SQL。同时在代码Review环节明确“导出接口禁止使用分页查询方法”。这类问题最好的解决方式其实不是排查，而是建立规范——所有导出接口都走独立的查询方法，不允许调用带分页的通用查询。

7. 分页参数设计的几个小习惯

最后分享几个我自己长期用下来的习惯，刚入行的同事照着做，基本能避开分页相关的绝大多数暗坑。

第一，参数名统一。项目里一旦出现pageNum、currentPage、pageIndex混用，就离事故不远了。我一般统一用pageIndex和pageSize，并且在API文档、前端请求封装、后端DTO三个层面保持一致。改一个名字的成本远低于排查一次数据错乱。

第二，日志里带上下文。分页相关的核心日志格式至少包含uid、pageIndex、pageSize、total、请求耗时这几个字段。线上排查问题时，没有日志里的pageIndex，你根本不知道用户当时翻到了哪一页。

第三，测试覆盖边界值。每个分页接口上线前，至少用例覆盖：第1页、最后一页、超出总页数1页、pageSize=1、pageSize=100、pageSize=0或负数、不传pageIndex的默认值。不超过5分钟能跑完，却能挡掉大量低级Bug。

第四，前端请求封装里把“页码重置”做成通用逻辑。我在项目里会在公共的请求层加一个mixins，里面统一处理pageIndex重置、空数据占位、错误重试。这样业务开发就不需要每次写分页列表时都重复处理这些边界，出错概率大大降低。

提示：凡是分页接口中涉及排序的，排序字段必须是三选一：主键、唯一索引、或者一个包含主键的复合索引字段。哪怕你允许用户按任意字段排序，后端也要强制“第二排序键为主键”，否则两个字段值相同时，MySQL不保证分页顺序稳定，翻页过程中就会出现同一条数据反复出现。

PageIndex这词看上去简单，但它背后牵涉的基数约定、边界处理、深分页性能、接口设计，每一层都有不少值得讲究的地方。我自己刚入行时也是踩了一轮才把这些要点串起来。希望这篇把关键路径梳理清楚，以后再做分页、调分页Bug时，能少走几步弯路。