PageIndex 这个单词放在不同人面前反应是完全不一样的。后端拿到它第一反应是“分页参数”前端看到它想到的是“列表当前第几页”数据库工程师脑子里浮现的可能是“聚簇索引的第几个页”。我最早被这个词坑到是在一个联调现场前端同学信誓旦旦说“第2页我传的 PageIndex1”后端同学坚持“我拿到的 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 与 PageNumber0-based 与 1-based 之争分页参数在真实项目里往往不止一种写法。有人用pageIndex有人用pageNum有人用pageNo还有人用currentPage。名字不统一还好说真正致命的是起始值不一致。0-based从 0 开始第 1 页是pageIndex0第 2 页是pageIndex1。这个习惯来自数组下标计算机天然习惯。1-based从 1 开始第 1 页是pageIndex1第 2 页是pageIndex2。这个更符合人类直觉毕竟没有人会说“请翻到第 0 页”。最麻烦的是不同框架、不同中间件的默认值完全不一样。我这里列一张常用框架的对照表大家感受一下差异框架/组件参数名起始值备注Spring Data JPApage0PageRequest.of(page, size)的 page 从 0 开始MyBatis PageHelperpageNum1从 1 开始等价于 0-based 的 page1ASP.NET GridViewPageIndex0服务端控件的页码索引从 0 开始Element UI / Ant Design 分页current或currentPage1前端组件通常从 1 开始展示自己写的接口不确定不确定最常见的 bug 源Spring Data JPA 里page0是第一页PageHelper 里pageNum1是第一页。前端用 Element UI 的current1表示第一页传参给 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 场景下传pageIndex2OFFSET2*10201-based 场景下传pageIndex3OFFSET(3-1)*1020。两者最终结果一样但中间参数完全不同。很多团队出问题就在这里后端文档写着“pageIndex 从 1 开始”代码里也老老实实写了(pageIndex - 1) * pageSize但某个中间层同学觉得“索引嘛就该从 0 开始”把参数悄悄减了 1 再往下传。结果就是前端用户的第 2 页后端收到 1中间层转成 0SQL 变成OFFSET 0——用户永远看到第一页。这种 bug 不查接口链路到最后一环根本找不到。所以我在实践中会做一个统一后端接口层显式接收“页索引”语义的参数并统一从 0 开始。这样OFFSET pageIndex * pageSize不需要减一逻辑直白也好和 Spring Data JPA、MyBatis 里的很多库直接对接。2.2 主流数据库和 ORM 里的分页实现对照先看原生 SQL。PostgreSQL 和 MySQL 都支持LIMIT ... OFFSET ...-- 第 3 页每页 10 条0-based 语义pageIndex2 SELECT * FROM orders ORDER BY id LIMIT 10 OFFSET 20;SQL Server 2012 之后推荐OFFSET ... FETCHSELECT * 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 开始 PageOrder page orderRepository.findAll(pageable);MyBatis 用 PageHelper 时PageHelper.startPage(3, 10); // 页码从 1 开始 ListOrder orders orderMapper.selectAll();用 C# 的 EF Core 时是 Linq 风格的Skip/Takevar 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 且 maxPageSize0 或负数会导致 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 排序第一页拿到最后一条记录的id1000。第二页查询SELECT * FROM orders WHERE id 1000 ORDER BY id LIMIT 20;数据库利用主键索引直接定位到id1000的位置然后向后读取 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 页时发的请求是?pageIndex1pageSize10。看起来正常。翻到第 3 页时是?pageIndex2pageSize10。这就是我们约定的 0-based 语义。第二步看后端 SQL。日志里对应第 2 页的 SQL 是SELECT * FROM content ORDER BY create_time DESC LIMIT 10 OFFSET 10;OFFSET 算得没问题LIMIT 也是 10。问题在哪第三步手动执行这条 SQL再看第 1 页的 SQLSELECT * 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?pageIndex0pageSize10响应{ 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 开始。接入后端pageIndex0的接口时如果没有一个显式的转换层很容易在传参时错位。我见过团队在 axios 拦截器里统一做params.pageIndex params.current - 1也见过直接改前端组件源码。哪种做法都行但必须落在文档里。第四个是单元测试。写几个不到 20 行的用例就能拦住 80% 的分页回归问题pageIndex0取第一页、pageIndextotalPages-1取最后一页、pageIndex越界返回合理结果、pageSize非法被校验拦截。这些用例比手工翻页靠谱得多。我个人这些年最大的体会是PageIndex 从来不是一个“写两行 SQL 就完事”的参数。它的语义定义、换算逻辑、排序稳定性、深分页性能、并发边界每一个环节都可能让线上出问题。与其每次联调都靠人肉核对不如在一开始就把规则定死用代码和实践去兜底。能在一个小参数上多想几步后面省下的是无数个深夜排查的头发。