PageIndex 这个单词，放在不同人面前，反应是完全不一样的。后端拿到它第一反应是“分页参数”，前端看到它想到的是“列表当前第几页”，数据库工程师脑子里浮现的可能是“聚簇索引的第几个页”。我最早被这个词坑到，是在一个联调现场：前端同学信誓旦旦说“第2页我传的 PageIndex=1”，后端同学坚持“我拿到的 PageIndex 明明是2”，两边吵了半小时，最后发现各自的页码定义差了整整一位。从那以后，凡是涉及分页的项目，我都会先把 PageIndex 的语义钉死，再谈后面的逻辑。这篇文章就想把 PageIndex 从头到尾讲透——它到底是什么、在不同框架里为什么表现不一致、从参数到 SQL 的换算逻辑有哪些坑、深分页为什么越翻越慢，以及我踩过一堆坑之后最终沉淀下来的分页接口设计规范。内容偏后端和全栈方向，但前端同学看了也能少走弯路。
1. PageIndex 的真实身份：分页参数、索引页还是页码索引？
1.1 一个词，三种语境
先说个容易混淆的事：PageIndex 在计算机领域其实有三种常见含义。
第一种是数据库层面的“页索引”。表空间、索引文件的数据是按页存储的，每个页有自己的编号，有时被称为 Page Index。SQL Server 的sys.dm_os_buffer_descriptors里就有page_id的概念，MySQL InnoDB 的聚簇索引页也有页号。这个“页”和分页查询里的“页”完全是两码事，但不少初学者会把它们搅在一起。
第二种是文档处理里的“页面索引”。PDF 解析、OCR 识别、Word 文档转换时，pageIndex常被用来表示文档中的第几页，用于定位或提取内容。比如用 PDF 库抽取第 5 页的文本，传入的 PageIndex 通常就是 4（从 0 开始）。
第三种才是开发里最常见的“分页页码索引”。列表接口中，前端请求第 3 页数据，pageIndex传 2 或者传 3，取决于后端约定。我们日常联调、排查性能问题、写 SQL 翻页，说的 PageIndex 99% 都是这个。
这三种语境本身就说明：PageIndex 是一个高度依赖上下文的名词。一旦接口文档里不写明“从 0 开始还是从 1 开始”，歧义马上就来了。我在代码评审时见过不少接口，参数定义写着pageIndex: 页码，就这四个字，不标默认值、不写起始值、不写最大值。这种接口上线后不出 bug 是运气，出 bug 是必然。
1.2 PageIndex 与 PageNumber：0-based 与 1-based 之争
分页参数在真实项目里往往不止一种写法。有人用pageIndex，有人用pageNum，有人用pageNo，还有人用currentPage。名字不统一还好说，真正致命的是起始值不一致。
- 0-based：从 0 开始，第 1 页是
pageIndex=0，第 2 页是pageIndex=1。这个习惯来自数组下标，计算机天然习惯。 - 1-based：从 1 开始，第 1 页是
pageIndex=1，第 2 页是pageIndex=2。这个更符合人类直觉，毕竟没有人会说“请翻到第 0 页”。
最麻烦的是，不同框架、不同中间件的默认值完全不一样。我这里列一张常用框架的对照表，大家感受一下差异：
| 框架/组件 | 参数名 | 起始值 | 备注 |
|---|---|---|---|
| Spring Data JPA | page | 0 | PageRequest.of(page, size)的 page 从 0 开始 |
| MyBatis PageHelper | pageNum | 1 | 从 1 开始，等价于 0-based 的 page+1 |
| ASP.NET GridView | PageIndex | 0 | 服务端控件的页码索引，从 0 开始 |
| Element UI / Ant Design 分页 | current或currentPage | 1 | 前端组件通常从 1 开始展示 |
| 自己写的接口 | 不确定 | 不确定 | 最常见的 bug 源 |
Spring Data JPA 里page=0是第一页，PageHelper 里pageNum=1是第一页。前端用 Element UI 的current=1表示第一页，传参给 Spring Data JPA 后端，如果中间不做转换，那你请求的“第 1 页”在后端眼里是“第 0 页”——数据错位就是从这种微小的不一致开始的。
1.3 全栈统一：一次定义，前后端共享
经历了多次翻页错乱之后，我的第一个经验是：分页参数的定义必须全栈统一，而且最好能用代码或接口文档工具强制约束。
统一的第一步是明确口语。“页码”和“页索引”是两个词：页码是人类看到的第几页，从 1 开始；页索引是程序里的第几个页，从 0 开始。如果你心里默认“页索引从 0 开始”，那么接口参数就该起名pageIndex而不是pageNum，避免和“用户认知里的页码”混淆。
第二步是让前后端使用同一份接口契约。可以用 OpenAPI/Swagger 注解写清楚pageIndex的默认值、最小值、说明；也可以在前后端共享的类型定义或 SDK 里直接规定。至少要在代码里留一个常量或注释。我在项目里习惯在 DTO 上顺手写清楚：
/** * 页索引，0-based，第一页为 0 */ @Min(0) private Integer pageIndex = 0;前端拿到这个定义就不会再猜。猜，是分页 bug 的起点。
2. 从 PageIndex 到 OFFSET：分页参数的换算逻辑与落地实现
2.1 换算公式：OFFSET 到底等于什么
接口收到pageIndex和pageSize之后，要把它翻译成数据库能理解的OFFSET和LIMIT。这一步看似简单，实则两个截然不同的公式对应两种语义：
- 如果
pageIndex从 0 开始：OFFSET = pageIndex * pageSize - 如果
pageIndex从 1 开始：OFFSET = (pageIndex - 1) * pageSize
举例：每页 10 条，用户要看第 3 页。0-based 场景下传pageIndex=2，OFFSET=2*10=20；1-based 场景下传pageIndex=3，OFFSET=(3-1)*10=20。两者最终结果一样，但中间参数完全不同。
很多团队出问题就在这里：后端文档写着“pageIndex 从 1 开始”，代码里也老老实实写了(pageIndex - 1) * pageSize，但某个中间层同学觉得“索引嘛，就该从 0 开始”，把参数悄悄减了 1 再往下传。结果就是前端用户的第 2 页，后端收到 1，中间层转成 0，SQL 变成OFFSET 0——用户永远看到第一页。这种 bug 不查接口链路到最后一环根本找不到。
所以我在实践中会做一个统一：后端接口层显式接收“页索引”语义的参数，并统一从 0 开始。这样OFFSET = pageIndex * pageSize不需要减一，逻辑直白，也好和 Spring Data JPA、MyBatis 里的很多库直接对接。
2.2 主流数据库和 ORM 里的分页实现对照
先看原生 SQL。PostgreSQL 和 MySQL 都支持LIMIT ... OFFSET ...：
-- 第 3 页，每页 10 条，0-based 语义，pageIndex=2 SELECT * FROM orders ORDER BY id LIMIT 10 OFFSET 20;SQL Server 2012 之后推荐OFFSET ... FETCH：
SELECT * FROM orders ORDER BY id OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY;这里有个细节：SQL Server 的OFFSET ... FETCH必须配合ORDER BY使用，没写ORDER BY直接报错。MySQL 和 PostgreSQL 不报错，但不写ORDER BY时返回顺序是不确定的，翻页必乱。我在后面第 4 章会专门展开讲排序稳定性对分页的致命影响。
ORM 层面，大家写的时候要注意框架的“页码语义”差异。Spring Data JPA 里这样写：
Pageable pageable = PageRequest.of(2, 10); // 第三页，从 0 开始 Page<Order> page = orderRepository.findAll(pageable);MyBatis 用 PageHelper 时：
PageHelper.startPage(3, 10); // 页码从 1 开始 List<Order> orders = orderMapper.selectAll();用 C# 的 EF Core 时是 Linq 风格的Skip/Take：
var orders = await ctx.Orders .OrderBy(o => o.Id) .Skip(20) // 跳过前 20 条 .Take(10) // 取 10 条 .ToListAsync();Skip/Take的本质也是 OFFSET/LIMIT，语义是“从 0 开始数”，需要自己算skipCount = pageIndex * pageSize。不同框架默认页码起始值不一致这件事，建议每个项目在启动阶段就拉齐，而不是等到联调再吵。
2.3 一个容易爆的冷门坑：整型溢出
这个坑我印象极深。某个列表接口上线一年后，突然有用户反馈“翻到最后一页，数据全乱了”。查了半天，最后发现是OFOFFSET` 计算时发生了整型溢出。
当时的代码长这样：
int offset = pageIndex * pageSize;看起来人畜无害。但注意，Java 的int是 32 位，最大值约 21.4 亿。如果pageIndex是 300 万、pageSize是 1000，乘积就是 30 亿，直接溢出变成负数。SQL 里OFFSET -1会出现什么行为？不同数据库不一致，有的报错，有的当成 0，有的返回异常结果——总之，用户看到的就是“数据乱了”。
修复方案很简单：乘积用long或者直接限制pageIndex的最大值，比如pageIndex * pageSize <= 1000000之类。分页查询本来就是为“浅分页”设计的，深分页的性能问题另说（第 3 章展开），但接口层面防住溢出是基本功。
long offset = (long) pageIndex * pageSize; if (offset > MAX_OFFSET) { throw new IllegalArgumentException("pageIndex too large"); }2.4 参数校验：别信任任何一端
分页参数是接口暴露面，恶意调用者或前端 bug 都可能传入离谱的值。常规校验至少包含这几条：
| 参数 | 规则 | 说明 |
|---|---|---|
pageIndex | >= 0 | 负数没有意义 |
pageSize | >= 1 且 <= maxPageSize | 0 或负数会导致 SQL 异常，超大值会拖垮数据库 |
pageIndex * pageSize | 不能超过安全上限 | 防止溢出和保护性限制深分页 |
maxPageSize我建议普通列表接口设置在 50~100 之间。有些接口允许导出全部数据，那就不该走分页接口，应该单独提供导出接口或异步任务。把pageSize放到 1000 的接口，等于把数据库压测能力直接暴露给客户端。
3. 深分页困境：为什么 pageIndex 越大接口越慢
3.1 数据库里的 OFFSET 到底做了什么
分页查询是开发必备技能，但很多人没有意识到OFFSET背后的代价。
当数据库执行LIMIT 20 OFFSET 1000000时，它绝不是“直接从第 1000001 条开始读”。在大多数实现里，数据库需要先读取前 1000020 行，然后丢弃前面的 1000000 行，只返回后面的 20 行。换句话说，OOFFSET跳过的行，数据库一个不少地扫描了一遍。
打个比方：你想看一本 1000 页书的第 900 页，普通的 OFFSET 分页方式相当于“每次都从第 1 页开始翻起，一路翻到第 900 页”。你翻到第 900 页需要的时间，和你翻到第 100 页需要的时间，差了好几倍。数据库和这类似，越到后面的页，扫描的数据越多，响应越慢。
如果没有合适的索引，这种扫描还会退化成全表扫描，那就不只是“慢”了，是灾难。
3.2 直观感受一下数据
以一张 1000 万行的订单表为例，主键是id，查询逻辑是ORDER BY id LIMIT 20 OFFSET ?。大致执行趋势如下（具体耗时取决于硬件和负载，但数量级可以参考）：
| 偏移量 | 大致耗时量级 | 说明 |
|---|---|---|
OFFSET 0 | 毫秒级 | 走主键索引，查 20 行返回 |
OFFSET 10000 | 数十毫秒级 | 扫描 10020 行，还能接受 |
OFFSET 1000000 | 几百毫秒到秒级 | 扫描 100 万行，明显变慢 |
OFFSET 9000000 | 秒级甚至更久 | 接近全表扫描，接口基本不可用 |
这不是危言耸听。真实业务里，“翻到第 10 万页”不常见，但 C 端产品如果数据量涨得快，“翻到第 5000 页”是完全可能的。到时候用户体验就是“越滑越卡，最后直接超时”。
3.3 优化方案：Keyset Pagination（游标分页）
深分页的经典解法是游标分页。思路很简单：不再用 PAGE OFFSET 跳过前面所有数据，而是记录“上一页最后一条数据的位置”，下一页查询时从那个位置之后开始取。
比如按主键 ID 排序，第一页拿到最后一条记录的id=1000。第二页查询：
SELECT * FROM orders WHERE id > 1000 ORDER BY id LIMIT 20;数据库利用主键索引直接定位到id>1000的位置，然后向后读取 20 条。不管你在第几页，查询都只看 20 条数据，耗时基本稳定，不会越翻越慢。
游标分页的代价也很明显：它依赖一个有序且唯一的键（通常是自增主键或时间戳），并且“跳转到任意页”变得困难。你想让用户一次性从第 1 页跳到第 5000 页，游标分页算不出OFFSET，做不到。
所以这俩方案不是替代关系，而是场景选择：
| 场景 | 推荐方案 | 原因 |
|---|---|---|
| 后台管理系统、报表列表 | 传统 OFFSET 分页 | 需要页码跳转第 N 页，数据量通常可控 |
| C 端 Feed 流、聊天记录、日志 | 游标分页 | 用户是“往下滑”，不需要页码，数据量大 |
| 数据量大但 UI 必须显示页码 | 混合方案 | 前几百页用 OFFSET，超出后改用游标或禁止跳转 |
混合方案是我在实际项目里比较推荐的一种取舍：展示页码是产品同学坚持的需求，但数据库承受不了深层偏移。那就在服务端做一个保护：pageIndex * pageSize超过某个阈值时，直接返回提示“数据量过大，请使用筛选条件”，或者自动切换到基于时间游标的“加载更多”模式。先保证系统不挂，再谈体验。
3.4 深分页之外：COUNT 查询要不要每次算
除了取数据本身，分页接口还有个常见性能卡点：统计总条数的那条SELECT COUNT(*)。很多分页接口返回total给前端用于展示总页数，这个 count 在大表上可能比查数据还慢。
如果业务上必须显示总页数，至少要给COUNT(*)的 WHERE 条件匹配的字段建索引，或者做缓存。如果是滚动加载场景，干脆去掉total，只返回hasMore即可。少一个 count，深分页的压力能小一大截。
4. 实战排查：一次由 PageIndex 引发的“翻页错乱”
4.1 现象：第 2 页出现了第 1 页刚见过的数据
那次事故发生在某个内容列表页。用户反馈：往下翻到第 2 页，看到第 1 页里已经出现过的一条内容；继续翻到第 3 页，又有一条第 1 页的内容混进来。起初以为是缓存问题，让运营清了 CDN，没用。后来有用户说“第 2 页少了 1 条数据”，事情性质就变了——这不是缓存问题，是数据查询逻辑的问题。
4.2 排查链路：从前端传参到 SQL 日志
我当时的排查链路大概是这样：
第一步，抓接口请求参数。浏览器 Network 面板里，用户翻到第 2 页时发的请求是?pageIndex=1&pageSize=10。看起来正常。翻到第 3 页时是?pageIndex=2&pageSize=10。这就是我们约定的 0-based 语义。
第二步，看后端 SQL。日志里对应第 2 页的 SQL 是：
SELECT * FROM content ORDER BY create_time DESC LIMIT 10 OFFSET 10;OFFSET 算得没问题，LIMIT 也是 10。问题在哪？
第三步，手动执行这条 SQL，再看第 1 页的 SQL：
SELECT * FROM content ORDER BY create_time DESC LIMIT 10 OFFSET 0;我把两条 SQL 的结果集都拉出来，逐条对比 ID，发现重复的记录在create_time上是完全相同的。比如第 1 页里有一条记录的create_time是2025-06-11 10:23:45，第 2 页里也有一条create_time一模一样的记录。排序只按这一个字段，数据库对这些相同值的记录返回顺序没有任何承诺，先返回哪条后返回哪条全看执行计划。于是在两次查询之间，有新的数据插入、或执行计划发生轻微变化时，相同的时间戳记录就可能“串位”。
第四步，继续往上查。为什么会产生这个排序不稳定？因为建表时create_time没有唯一性；又有人觉得“列表按发布时间排就行”，没加二级排序。于是ORDER BY create_time DESC对相同值的行来说，后续顺序是随机的。
4.3 两个 bug 叠在一起，单独查都正常
这里要特别说明：PageIndex 的语义其实没有错，OFFSET 算得也对；真正出错的是“排序不稳定”和“并发写入”叠加。但如果没有从参数到 SQL 的完整链路排查，很容易把锅甩给分页参数。
修复方案我做了两个：
第一，排序必须唯一。把查询改成：
SELECT * FROM content ORDER BY create_time DESC, id DESC LIMIT 10 OFFSET 10;加上id DESC作为决胜排序后，每一行的顺序都是确定的，翻页不会因为相同时间戳而“串行”。这是一个基础但极其常见的坑，几乎每张业务表的分页查询我都建议强制加唯一排序键。
第二，参数语义前后端明确化。虽然本地排查发现 pageIndex 换算没毛病，但这个接口的文档里只写了“页码”，没有说明起始值。我要求接口维护方把注释补齐，并加上参数校验。不直接修 bug 的团队，迟早会在另一个地方踩同样的坑。
4.4 这个坑为什么难查
复盘这次事故，最有价值的不是修复本身，而是“难点在哪里”。前端参数正常、后端 OFFSET 换算正常、SQL 语法正常，但翻页结果就是错乱。原因在于两个看起来各自无害的问题叠加：排序不唯一 + 新增数据的写入影响查询结果。这类问题在常规的单元测试里极难触发，因为单页查询结果看起来都是对的，只有连续翻页并比对“去重后的集合”时才会暴露。
所以后来我在项目里加了一条测试用例：模拟连续翻页，收集 5 页数据，断言 ID 无重复、无遗漏。这个用例成本不高，但能有效把“翻页错乱”挡在上线之前。
5. 设计一个被长期维护的分页接口：我的取舍与规范
5.1 我最终选用的约定
踩过这么多坑之后，我设计分页接口时会直接定下这几条约定，不留给联调阶段去“商量”：
pageIndex从 0 开始，第一页传 0。理由：和 OFFSET 的换算直白，和 Spring Data JPA、多数前端表格组件的“内部下标”习惯对齐。pageSize默认 10，最大 100。理由：保证浅分页场景的响应速度和 DB 压力。- 响应体必须返回
pageIndex、pageSize、total、totalPages，前端展示页码时用totalPages自己算 1-based 页码，不让“0”暴露给用户。
这个约定的关键在于：程序内部统一 0-based，用户界面展示统一 1-based，转换逻辑放在前端展示层或后端 VO 组装层，但永远不要在 SQL 层做“减一再加一”的反复横跳。
5.2 请求与响应结构
接口请求：
GET /api/contents?pageIndex=0&pageSize=10响应：
{ "items": [ { "id": 1, "title": "标题1", "createTime": "..." } ], "pageIndex": 0, "pageSize": 10, "total": 12345, "totalPages": 1235 }totalPages的计算公式是(total + pageSize - 1) / pageSize。注意：如果pageIndex大于等于totalPages，接口不要返回空数组了事，最好给出明确提示或直接归一化到最后一页。很多前端在“删除若干条数据后仍在第 5 页”的场景下会请求一个已经不存在的页码，后端弹回空列表，前端就显示“暂无数据”，体验很差。
5.3 排序稳定性的强制要求
无论用什么分页方案，我都会在项目规范里加一条硬性要求：任何分页查询的 ORDER BY 必须包含唯一性字段。业务字段可以随便排序，但最后一个排序键必须是主键或唯一索引。
反面教材：
ORDER BY create_time DESC正面写法：
ORDER BY create_time DESC, id DESC这条规则几乎零成本，但能杜绝一大类翻页重复/漏数据的 bug。凡是列表接口，代码评审时我都会专门看这一条。
5.4 容易被忽略的收尾细节
再分享几个和 PageIndex 看起来无关、实际关系很大的细节。
第一个是total的查询优化。超大表的 count 很慢，如果接口只是给 C 端滚动加载用，建议砍掉 total 和 totalPages，只返回hasMore: true/false。如果必须展示页码，count 查询要确保 WHERE 条件能走索引。
第二个是并发写人下的分页意义会减弱。像“最新文章列表”这种高频插入场景，OFFSET 分页天然无法保证“翻页期间数据不变”。用户在第 1 页看到 10 条，30 秒后再翻第 2 页，期间新插入的数据把旧数据挤到第 2 页，用户就会觉得“内容重复了”。业务能接受就把“页码”改成“游标”，不能就至少优化排序的唯一性，并尽量让列表接口只读最近 N 天数据。
第三个是前端组件和后端 SDK 的默认值要一致。不少前端分页组件自己会维护一个 current/page，默认从 1 开始。接入后端pageIndex=0的接口时，如果没有一个显式的转换层，很容易在传参时错位。我见过团队在 axios 拦截器里统一做params.pageIndex = params.current - 1，也见过直接改前端组件源码。哪种做法都行，但必须落在文档里。
第四个是单元测试。写几个不到 20 行的用例就能拦住 80% 的分页回归问题：pageIndex=0取第一页、pageIndex=totalPages-1取最后一页、pageIndex越界返回合理结果、pageSize非法被校验拦截。这些用例比手工翻页靠谱得多。
我个人这些年最大的体会是：PageIndex 从来不是一个“写两行 SQL 就完事”的参数。它的语义定义、换算逻辑、排序稳定性、深分页性能、并发边界，每一个环节都可能让线上出问题。与其每次联调都靠人肉核对，不如在一开始就把规则定死，用代码和实践去兜底。能在一个小参数上多想几步，后面省下的是无数个深夜排查的头发。
