PageIndex，一个前端传参、后端接收、数据库算偏移量的整数。做过分页功能的开发，没有人能绕开它。但就是这样一个看似人畜无害的参数，踩过的坑可真不少：前端默认从1开始，后端按0处理，列表直接错位；数据量到了几十万，翻到后面几页接口越来越慢；用户点下一页，结果返回了重复数据……这些问题的根源，往往都指向PageIndex这个“小数字”背后的设计细节。这篇内容，我就围绕PageIndex拆开讲讲分页这件事的前因后果，从它是谁、为什么会产生歧义，到边界异常怎么兜底、深分页怎么优化，再到接口返回体怎么设计，一次说透。适合正在写列表接口的后端、对接分页组件的前端，以及被线上分页Bug折腾过的全栈同学参考。

1. 从一个页码参数说起：PageIndex背后的三重需求

1.1 为什么一定要有“页码”这个东西

先说一个最原始的问题：为什么不能一次性把数据全查出来返回给前端？

因为数据量根本不允许。一个电商订单表，几百万行很正常；一次全量返回，光是序列化成JSON就要吃掉大量内存，网络传输可能得按秒计。更重要的是，用户的屏幕一次只能看到几十条，把几百万条数据全塞给浏览器，既浪费又卡顿。所以分页的本质，是**“按需切分数据”**——每次只取一小块，用户要看更多，再按某个规则去取下一块。

而“按某个规则去取下一块”，就是PageIndex存在的意义。它是客户端与服务器之间约定好的“页码游标”：我当前在数据的第几块，你以此为起点，去取对应块的数据。没有PageIndex，服务器就不知道用户想要的是哪一块；没有PageIndex，也不存在高效的数据切片方案。所以本质上，PageIndex是一个跨端协议字段，它连接了用户的浏览行为和服务器的查询逻辑。

1.2 PageIndex与PageSize必须成对出现

只谈PageIndex是没有意义的，它必须和PageSize（每页条数）一起使用。两者的关系可以用一个简单公式概括：

offset = (PageIndex - 1) × PageSize 或 offset = PageIndex × PageSize

注意这公式里的减“1”和不减“1”，这就是无数Bug的起点。前者是按“用户视角从第1页开始”设计的，后者是按“开发者视角从第0页开始”设计的。两个体系本身都没错，错的是混用。

举个例子就明白了。假设PageSize=20，用户想翻到第3页：

• 如果接口约定PageIndex从1开始，那第3页的偏移量应该是 (3-1)×20=40，也就是跳过前40条，取第41到第60条；
• 如果接口约定PageIndex从0开始，那前端应该传 pageIndex=2，后端算出来的偏移量也是 2×20=40。

看到没有，后端怎么写公式，取决于前端传什么。而前端写什么，取决于接口文档怎么定义。这一环扣一环，任何一环想当然，数据就对不上了。

1.3 一句话说清PageIndex的“岗位职责”

如果非要用一句话定义它，我会说：PageIndex是“你希望从第几块数据开始读”的编号。它本身不包含任何业务含义，不知道数据总共有多少，也不知道当前在第几页，它只是请求参数。真正的“当前页”“总页数”“总条数”，是服务器通过查询结果计算后，再通过响应体告诉前端的。

所以也就牵出了一个非常常见的设计误区：有人会把前端传的PageIndex原样存进数据库表里，作为业务字段。这个做法我强烈不建议。PageIndex是查询条件、是临时状态，不是业务实体。它应该只出现在请求参数、计算偏移量、以及响应回显这几个环节中，不需要持久化。

2. 0基还是1基：PageIndex最经典的分歧现场

2.1 两种设计的底层逻辑完全不同

PageIndex从0开始还是从1开始，不是随便拍脑袋定的，它背后对应完全不同的使用场景。

从1开始，契合的是人的阅读直觉。用户打开页面看到的第一屏，自然就是“第1页”。下拉列表显示的页码、面包屑里的“第X页”、URL里的 ?page=1，全都是用户能直接理解的语义。这种模式在前端UI组件里非常常见，比如ElementUI、Ant Design，它们的页码默认都是1起。

从0开始，契合的是数组的索引习惯。在编程世界里，数组下标从0开始是常识。第一个元素的index是0，第一页的PageIndex是0，逻辑自洽。后端分页组件比如MyBatis PageHelper，参数 pageNum 默认从1开始，但很多封装的底层PageIndex直接传0。Spring Data的PageRequest.of(0, 10) 明确的从第0页开始。用0基的好处是偏移量计算不需要减1，稍微省了一次算术操作，更重要的是和编程语言的索引习惯对齐，后端处理时不需要格外小心。

说实话，两种方案在性能和复杂度上几乎没有区别。真正的区别在于，整个链路里所有人是不是遵循同一个约定。

2.2 混用带来的经典病象

我接手过一个项目，前端用的分页组件是从1开始的，用户点击第2页，前端传 pageIndex=2。后端拿到参数后，按照0基公式计算偏移量：offset=2×20=40。这算出来其实已经是第3页的数据了，前端展示的时候，用户就发现“点第2页，看到的内容和第3页的重复了”。反过来，如果后端按1基减1，但前端传的是0基的0，那第1页的数据就完全取不到，列表直接空白。

这类问题难排查的点在于：它不在任何环节报错。接口正常返回、状态码200、数据格式也对，只是数据内容错位。如果不加日志比对前端传递值、后端偏移量计算过程，光靠肉眼很难定位。

我的排查建议是，遇到类似“列表内容错位”的情况，第一件事就是对比三组数字：

只要这三者逻辑不一致，问题往往就出在0基/1基混用或者参数名映射错误上。

2.3 我推荐的做法：接口统一用0基，前端UI负责转换

踩过多次坑之后，我现在的标准是：对外暴露的API全部用0基PageIndex，前端分页组件通过配置把用户看到的“第1页”映射为pageIndex=0。好处有三个：

一是后端切分数据的逻辑足够纯粹，不做任何“用户友好”的转换，偏移量就是 PageIndex×PageSize，没有任何减1的操作。二是API层面的0基与编程语言数组索引一致，无论谁来接管后端，都不容易算错。三是前端组件只需要在交互层处理“用户第1页”VS“接口第0页”这一层语义转换，属于UI层的职责，而这层转换是组件库官方支持的，有成熟约定。

需要注意的是，在接口文档里必须白纸黑字写明“PageIndex：从0开始”。不要觉得这句话多余。我在项目中见过太多后端同事说“我们默认从1开始吧，用户看着也舒服”，这种好心往往就是隐患的开始。

3. 边界与异常：PageIndex容易翻车的三个场景

3.1 越界请求：PageIndex传负数或超大值怎么办

分页参数面临的第一个恶意/非恶意挑战，就是越界。

用户手动改URL，把 p=0 改成了 p=-1；或者爬虫脚本自动遍历接口，pageIndex 从0一直循环到几千。这些请求如果没有校验，会出现两种情况：负数导致偏移量为负数，数据库直接报错（SQL里OFFSET为负数）；超大PageIndex导致偏移量巨大，数据库为了计算LIMIT后的OFFSET，会扫描并丢弃大量行，接口被拖慢。

所以PageIndex的校验是必须做的。我习惯在服务入口统一处理：

• PageIndex小于0时，直接按0处理；
• PageSize小于1时，按默认值（如20）处理；
• PageSize超过上限（如100）时，截断到100，防止有人恶意传大分页；
• 如果传参不是数值类型，按非法参数返回400或启用默认值。

这些校验可以通过注解（如@Min(0)）和手动判断双重保障，放在网关或Controller入口，保证任何业务代码拿到的PageIndex都是合法值。这个处理不是逻辑复杂，而是防御性编程的底线。

3.2 最后一页的“空结果”和“数据不足”

当用户翻到最后一页时，可能会遇到两种情况：这一页刚好满页；或者这一页只有2条数据，剩下的位置是空的。对于前端来说，列表组件需要能正常展示不足PageSize数量的数据，并且根据当前返回条数小于PageSize这一信号，判断“没有更多了”，让用户停止继续点击加载。

还有更极端的：用户在第2页停留了很久，这期间数据被删除了，等他想第3页时，发现传过去的PageIndex对应的offset已经完全超出范围，返回空数组。这时候前端要友好提示“没有更多了”或“列表已更新，回到第1页”，而不是白屏或报错。

后端在处理空结果时的返回体，也应该统一规范。比如返回一个包含 total、pageIndex、pageSize、list 的标准结构，即使list为空，其他字段也必须回填，尤其是total，前端要根据总数判断列表是空了还是数据还没加载出来。

3.3 数据动态变化导致的分页漂移

分页漂移是分页系统中最难观测的一个问题。场景是这样的：列表按“创建时间”倒序排列，每页20条。用户在第1页看到了A、B、C三篇文章，在他翻页的这几秒里，管理员删除了一条老数据，同时在顶部插入了一条新数据。数据库自然是按照当前数据状态重新排的序，于是用户在第2页拿到的数据中，原本在第1页末尾的第20条数据，因为前19条里少了一条，顺势挤进了新“第2页”的第一位。用户实际看到的是：同一篇内容出现在了两页里。

解决方案有几种：最简单的是请求时强制刷新，让列表一次性重新加载，牺牲一定体验；稍微好用的是引入“上一页最后一条记录的排序值”作为游标，也就是游标分页；如果业务相对简单，也可以让前端在翻页时带上第一页最后一条记录的ID，后端通过主键过滤避免重复。

实际上，绝大多数业务场景并不会严格追求“翻页不重不漏”——用户真的一页页翻到很后面的场景很少。但对于内容流、搜索结果这类持续滚动浏览的场景，分页漂移直接影响用户体验，我会强烈建议用游标分页替代传统OFFSET分页，后面详细展开。

4. 深分页与性能优化：当PageIndex变大时接口为什么变慢

4.1 OFFSET分页的代价

传统分页查询的SQL大概长这样：

SELECT * FROM t_order ORDER BY create_time DESC LIMIT 20 OFFSET 6000;

这表示取第301页的数据，offset为6000。表面上看起来是只取20条，但MySQL内部的做法是：按ORDER BY排序之后，从头扫描，跳过6000条，再取20条。也就是说，OFFSET越大，扫描和排序的行数就越多，查询就越慢。到了页数很深的时候，即使你的表的总行数不大，排序的临时表和扫描开销也足以拖垮接口。

我遇到过实际案例：一张30万行的订单表，按创建时间倒序分页，前50页接口平均耗时50ms，翻到第5000页时，单次查询耗时接近2秒。用户并不会一直翻到5000页，但恶意遍历API的脚本、导出功能、或者后台管理系统的“全量列表翻看”，都会持续打到深分页这种场景。这也是为什么很多人发现，系统平时笑嘻嘻，一跑批量导出就卡死的原因之一。

4.2 游标分页：彻底绕开OFFSET

既然深分页的瓶颈在于“跳过大量行”，那性能最好的方案就是不跳过，直接定位到“上一次读到的位置”继续往下读。这就是游标分页（Keyset Pagination / Seek Method）。

思路非常直观：用户翻到下一页时，前端带上“当前这页最后一条数据的排序字段值”，后端用这个值作为查询起点。比如按主键ID倒序分页：

SELECT * FROM t_order WHERE id < #{lastId} ORDER BY id DESC LIMIT 20;

注意，SQL里没有OFFSET。数据库利用主键索引直接定位到lastId的位置，然后继续向后扫描20条。无论查询第100页还是第10000页，扫描行数都是20行，性能基本恒定。这是分页性能优化上的一个关键认知：把“翻页多少”变成“当前位置在哪”，查询成本与翻页深度彻底解耦。

游标分页也有它的限制：它不再支持“一次性跳到任意页”（页码概念被弱化），只能一页一页往下翻；排序字段必须是唯一、稳定、能被索引命中的（常见的是主键ID或创建时间+ID组合）；如果同时有多个排序字段，游标条件也要相应变为组合比较。对于“加载更多”型列表、搜索结果流、Feed流这类天然顺序浏览的场景，游标分页是远优于传统分页的选择；对于带页码跳转的管理后台，还是老老实实OFFSET分页加合理限制更合适。

4.3 如果必须深翻页，还能怎么救

游标分页虽好，但不是所有业务都能改造。如果项目必须保留页码分页，靠优化SQL本身能提升的有限，更可行的方向是：

尽量让排序字段走索引，避免文件排序。创建时间字段建议建联合索引，比如(create_time, id)。避免对无索引列进行排序分页，全表排序时深分页代价会更大。提前拦截大页码，比如超过100页统一拒绝，很多前端列表根本翻不到那么深。对于后台导出类任务，不要走深分页循环，而是直接用一次性全量查询、或者用游标循环落盘，配合异步任务和临时文件下载。

在我实际项目中，最常用又不伤筋动骨的组合方案是：普通列表用OFFSET分页，且PageIndex超过一定阈值后前端隐藏跳页输入框、展示为“仅加载更多”；高频流式场景用游标分页；导出、全量扫描用Stream模式或游标模式跑。这套组合基本覆盖了几乎所有分页场景的性能需求。

5. 一个良好设计的PageIndex响应结构长什么样

5.1 请求参数与响应体缺一不可

很多分页接口设计不当，最直接的体现就是响应体里只有一个list。前端想判断还有没有更多，做不到；想显示总条数，做不到；想回显“当前第X页”，还要自己脑补。本来分页就是交互强相关的功能，没有配套元数据，等于把活儿甩给了前端。

我推荐的最小完整响应体设计如下：

{ "code": 0, "message": "success", "data": { "list": [], "total": 150, "pageIndex": 1, "pageSize": 20, "totalPages": 8, "hasNext": true } }

字段含义非常明确：list是当前页数据；total是总条数；pageIndex是当前请求的页码；pageSize是每页条数；totalPages是总页数，服务端算好给前端；hasNext是是否还有更多，强烈建议后端返回，让前端少做一次 total > (pageIndex+1)*pageSize 的判断。

5.2 PageIndex在接口中的参数风格选择

关于分页参数的命名风格，常见的还有 page、p、pageNo、pageNum、pageIndex、pageNumber、current……我见过同一套系统里出现三种写法的，前端每次接入新接口都要对着文档确认一遍，极其痛苦。

我的习惯是，团队内统一一种命名，写进接口规范文档。服务端接收参数固定用 pageIndex 和 pageSize；响应返回时也用同样的命名，不要请求传pageIndex、返回叫currentPage，前端又要再做一次映射。另外，URL上的可见分页参数我建议短小一点，比如用 ?page=1&size=20，而POST接口的JSON body里用 pageIndex / pageSize。不同传输场景用不同的参数名没有问题，但应固定下来，同时保持含义清晰。

5.3 回显与前端状态同步

这里还必须提一个问题：用户刷新页面之后，列表应该停留在哪一页？

如果你只是把pageIndex塞进URL的query里，刷新后前端重新拉接口、后端原样解析，PageIndex本身没有问题。但要注意的是，用户在列表内做了筛选、排序之后，原来的PageIndex可能已经失效，如果不重置为0，用户会看到一个奇怪的空列表或中间页。这类问题的本质是分页状态与查询条件状态强耦合。通用的做法是：任何筛选条件变化，PageIndex重置为0（或1，看约定）；任何排序变化，同样重置；翻页行为才单独变更PageIndex。这个规则前端状态管理里可以做统一封装，避免每一次分页请求都去手动判断。

6. 常见分页问题排查实录，直接拿来对照

6.1 高频问题速查表

我在团队内带人的时候，整理过一张分页问题排查清单，很多“疑难杂症”对照一下就能找到方向。这里列成表格，供大家直接参考：

6.2 一次典型的分页Bug复现与修复笔记

拿其中一个Bug做完整复盘。背景是一个资讯列表页，前端Ant Design的分页组件，默认页码从1开始。后端用Spring Data JPA，PageRequest默认从0开始。上线后收到的用户反馈是：点击第2页和第3页，部分内容重复。

刚开始接手时，只看后端日志完全找不到问题：SQL查询正常、总数对得上、接口报错为零。后来让前端在浏览器里打印请求参数，才发现Ant Design传的是 pageNum=2，而后端定义的是PageIndex字段，中间还有一层封装把pageNum放进pageIndex里，但没有做减1转换。后端的PageIndex=2被当作“第2块数据”（0基），偏移量是2×20=40；用户想去的第二页应该是偏移量20。前端展示的每一页都被推迟了1页，翻到后面自然和前一页尾巴重复。

修复方式分两步：在后端入口加一个统一拦截转换，检测到前端传来1基页码时自动减1映射为0基PageIndex；同时在接口文档中明确定义，所有API的pageIndex一律从0开始。现在来看，这个Bug不在算法复杂度，而完全在跨端语义歧义上。分页是老话题，但围绕PageIndex的沟通失误，到今天依然在新项目里反复发生。

6.3 排障过程中容易被忽略的细节

排查分页问题时，有几个点特别容易被忽略，值得单独强调。

一是总数COUNT的SQL和列表SQL的条件必须完全一致。很多时候总数和列表条数对不上，是因为COUNT没带权重的过滤条件，或者JOIN去重不完整。总数错了，一切基于总数的页码渲染都错。

二是多租户/多店铺场景下别忘了追加租户过滤条件。分页SQL如果漏了租户条件，偏移量就会跨租户错乱，而且这种问题往往只在特定租户下复现，隐蔽性极强。

三是分页排序字段是否为唯一值。如果只按一个非唯一字段排序，比如只按create_time排序，当两条数据create_time相同时，它们的先后顺序是不确定的，就会出现列表排列随机漂移、翻页重复或漏掉数据。解决方法是排序字段最后都以主键ID兜底，确保唯一排序。这个经验我认为是新手最容易踩的隐形深坑。

四是真的要到前端控制台里看一遍网络请求的完整参数和链路，别只盯着后端日志。很多分页问题本质上是参数传递链上的问题，包括网关层清洗参数、HTTP框架自动绑定、JSON字段命名不一致等。把“请求时实际生效的PageIndex值”确认清楚，比盲目加索引、改SQL有用得多。

7. 关于PageIndex，最后想说的实操心得

聊了这么多，我最想表达的还是那句话：分页的真正难点不在于技术复杂度，而在于约定与理解的一致性。PageIndex只是一个小小的参数，但从前端组件的翻页行为，到接口参数的命名与语义，再到后端偏移量计算、SQL性能的取舍，整个链路里只要某一环想当然，就会出现让人头疼的老大难Bug。

我个人的习惯性做法，是每个项目的接口文档里，都明确标注“pageIndex从0开始”这一条约定；后端接收分页参数时统一转换成标准内部对象，绝不让原始参数散落各处；提供一套统一的分页响应体，把所有元数据一次性返回。实现这些，代码量很小，却能帮团队省下大量联调、返工、线上排查的时间。

如果你问我，分页方案是选OFFSET还是选游标、PageIndex从0还是从1、返回结构带哪些字段，我的态度向来是“没有银弹，但要有一套默认标准加清晰的决策依据”。把底层机制吃透、把坑位提前识别出来，再结合业务形态做选择，比临时抱佛脚去修线上问题从容太多。