企业官网建设流程全解析

PageIndex，翻译成大白话就是"当前在第几页"。这个字段几乎出现在所有带列表、表格、分页器的系统里，从后台管理系统的订单列表，到前台的商品列表，再到移动端瀑布流式的触底加载，背后都离不开这个小小的参数。但就是这么个看起来不起眼的值，恰恰是前端最容易读错、后端最容易算错、数据库最容易卡死的地方。它在不同框架里的语义还不一样，有的从 0 开始，有的从 1 开始，一不留神就是线上事故。

这篇文章不聊虚的，只围绕 PageIndex 这一个点展开：它到底解决什么问题，前后端怎么约定才不会打架，后端怎么把它翻译成一条高效的 SQL，以及当数据量上来之后，为什么"翻到第 100 页"就可能把数据库拖垮。我会把我这些年全栈开发里跟分页反复缠斗的经验、踩过的坑、沉淀下来的方案一次性讲清楚，适合正在写第一个列表接口的新手，也适合想优化已有分页逻辑的工程同学参考。

1. 先搞懂 PageIndex 的业务本质：分页到底在解决什么问题

1.1 列表数据的三个核心数字

任何一个带分页的列表，无论界面长什么样，底层都离不开三个数字：当前页码（PageIndex）、每页条数（PageSize）、总条数（Total）。这三者的关系简单到了近乎朴素的地步，但整个分页逻辑都是围绕它们转的。

PageIndex 决定用户当前看哪一段数据；PageSize 由产品或者前端决定每屏展示多少条，常见的有 10、20、50；Total 则是后端在查询数据时同步统计出来的结果集大小。有了这三个值，前端才能画出页码条、计算出总页数、判断"下一页"按钮是否应该置灰，后端才知道要跳过多少条、取多少条。

我见过很多新人写接口时只返回了当前页的 list，把 total 漏了，结果前端页码条永远只有一页，翻都翻不动。所以我说，分页接口的返回值里，list 只是基础，total 才是灵魂，缺了它整个分页组件就是个摆设。

1.2 为什么不能一次性返回全部数据

有人会问，数据量不大时直接全量返回不行吗？答案是短期的确可以，但千万别养成这个习惯。我先举个生活化的例子：你去图书馆借书，图书管理员不会把整个书库的几万本书一次性搬到你面前让你挑，而是按书架、按区域引导你浏览；你需要的是"某一层的某个区域"，而不是"全部的书"。列表接口同理。

一次性返回全部数据有几个很现实的问题。第一是网络传输，一条记录哪怕只有 200 字节，一万条就是 2MB，移动端用户流量焦虑是真实存在的。第二是渲染，前端一次性把一万条 DOM 塞进页面，卡顿是必然的，除非你额外做虚拟滚动这类优化，但那已经是另一套复杂度了。第三是服务端内存和数据库压力，全量查询意味着更多的结果集缓存和更大的网络 IO。

分页的本质就是把"一次干完的事"拆成"每次只干一小段"，以极小的时间复杂度代价换取系统整体可控的压力。这个思想跟任务的分解、批处理是一个道理，它不只是用户体验问题，更是工程的容量规划问题。

1.3 分页的两种形态：真分页和假分页

我在很多项目里见过所谓的"假分页"——后端一次性把所有数据返回给前端，前端拿到完整数组后用 JS 自己截取当前页显示。数据量几百条时这么做无所谓，但一旦过万，接口耗时和内存占用都会肉眼可见地恶化。

与之对应的"真分页"，指的是后端根据 PageIndex 和 PageSize 真正去数据库里查那一小段数据。两句话的区别背后是架构选择的差异：假分页把性能压力丢给了浏览器，真分页把压力留在了后端可控范围。我的建议是，除非是纯静态配置数据，否则所有列表接口一律做真分页；这不仅是习惯，更是一种默认的安全策略。

判断一个项目是否该升级分页方式，就看它的数据增长速度。内部管理系统一个月几千条订单，假分页也能撑住；但 C 端产品一个促销活动就可能产生几十万条记录，真分页是唯一选择。

2. 前后端约定：pageIndex、pageSize、total 一个都不能少

2.1 一套可以沿用多年的入参定义

做全栈这几年，我慢慢沉淀出了一套个人偏好的分页入参规范，基本上新项目可以直接抄作业。前端请求时传两个参数：pageIndex 表示第几页，从 1 开始；pageSize 表示每页条数，默认 20，上限 100。后端返回值固定为三个字段：list 是当前页数据，total 是总条数，totalPages 是总页数。

对应的 JSON 结构大概是这样的：

{ "code": 0, "data": { "list": [ { "id": 101, "name": "张三" } ], "total": 356, "totalPages": 18, "pageIndex": 1, "pageSize": 20 } }

totalPages 虽然前端可以用 total 除以 pageSize 自己算出来，但后端顺手返回它并没有坏处，反而能省掉前端处理除法和取整的边界逻辑。做接口设计时，多返回一点"对方本来就要算"的字段，是避免重复劳动和计算不一致的好习惯。

2.2 从 0 开始还是从 1 开始的隐形陷阱

这是 PageIndex 最容易踩坑的地方，没有之一。不同框架、不同组件库对页码的语义定义是完全不同的：Bootstrap Table 的 pageNumber 从 1 开始，Ant Design 的 current 从 1 开始，Element UI 的 currentPage 也从 1 开始；但 Spring Data 的 Pageable 是 0 基的，第一页是 page=0；一些早期的分页插件也沿用了数组下标习惯，从 0 开始。

前后端一对接，问题就来了：前端传 pageIndex=1 表示第一页，后端用 Spring Data 的 PageRequest.of(1, size) 一接，实际查的却是第二页的数据。这种 bug 不会立刻暴露，往往是用户翻了几页之后发现列表错位、内容重复或者缺失，排查起来特别费劲。

我给团队的约定是：对外 API 统一从 1 开始，因为用户能感知的最小页码就是 1，"第 0 页"在任何 UI 上都解释不通；至于内部框架如果用了 0 基页码，在后端做一次减法转换，绝不让 0 基语义穿透到接口层。

2.3 边界条件必须提前写在接口文档里

分页接口的边界条件如果不在文档里写清楚，前后端就会各自发挥，最后线上互相甩锅。我一般会要求文档里至少明确这几条：pageIndex 最小值为 1，小于 1 时后端直接按 1 处理；pageSize 有上限，超限就截断到最大值；total 为 0 时依然返回空 list，pageIndex 固定为 1；排序字段必须是稳定的，不能只用一个容易重复的列排序。

别看这几条不起眼，它们其实是分页接口的"宪法"。有了明确的边界，前端就不需要写一堆兜底逻辑，后端也不用担心被传入一个 pageSize=100000 的恶意参数把服务搞挂。接口设计本质上就是契约设计，契约越清晰，联调成本越低。

3. 后端接口落地：从 PageIndex 到 SQL 的完整拆解

3.1 参数接收与基础校验

后端拿到 PageIndex 后的第一件事不是算偏移量，而是做参数校验。原因很实际：用户可能手动改 URL 上的参数，也可能有爬虫乱传数据，不校验直接进 SQL，轻则返回奇怪结果，重则触发深分页把数据库拖垮。

以 Java 的 Spring Boot 为例，一个标准的接收方式是这样：

@GetMapping("/users") public Result<PageResult<UserVO>> listUsers( @RequestParam(defaultValue = "1") int pageIndex, @RequestParam(defaultValue = "20") int pageSize) { if (pageIndex < 1) { pageIndex = 1; } if (pageSize < 1 || pageSize > 100) { pageSize = 20; } int offset = (pageIndex - 1) * pageSize; List<User> rows = userMapper.selectPage(offset, pageSize); long total = userMapper.countTotal(); return Result.ok(new PageResult<>(rows, total, pageIndex, pageSize)); }

Python 的 FastAPI 写法也类似，但可以用 Query 的 ge 和 le 参数直接声明约束，能省掉不少手写代码：

@app.get("/users") def list_users( page_index: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), ): offset = (page_index - 1) * page_size rows = db.execute("SELECT * FROM users ORDER BY id LIMIT ? OFFSET ?", (page_size, offset)) total = db.execute("SELECT COUNT(*) FROM users").fetchone()[0] return {"list": rows, "total": total, "pageIndex": page_index, "pageSize": page_size}

校验的核心思路是"错我不择路"：无论前端传什么，后端都要能把参数拉回合法区间，而不是带着非法值继续跑。这样既保护了数据库，又保证了接口行为的确定性。

3.2 offset 的计算与 SQL 翻译

计算 offset 是整个分页逻辑里最没有技术含量但最容易出错的一步。它取决于你选的是 1 基还是 0 基约定。如果 pageIndex 从 1 开始，那么要跳过前面 (pageIndex - 1) * pageSize 条；如果从 0 开始，直接乘 pageIndex * pageSize 就对了。换句话说，1 基页码要在 0 基的偏移公式里先减一个 1，这个减出来的"1"就是无数 off-by-one bug 的策源地。

在 SQL 层面，不同数据库的写法还不一样。MySQL 的语法是 LIMIT 偏移量, 条数，PostgreSQL 是 LIMIT 条数 OFFSET 偏移量，SQL Server 要用 OFFSET...FETCH NEXT。以 MySQL 为例：

SELECT id, name, status, created_at FROM user WHERE status = 1 ORDER BY id ASC LIMIT 20 OFFSET 0;

当 pageIndex=1、pageSize=20 时，offset 是 0，取第 1 到 20 条；当 pageIndex=2 时，offset 是 20，取第 21 到 40 条。逻辑清晰，但一旦前端按 0 基传参，而后端按 1 基算，第一页数据就会整页丢失，我实际排查过好几次这种问题，最后都是拿着接口日志和前端参数对比才发现的。

3.3 总条数和总页数的计算细节

分页接口的第二条 SQL 通常就是 COUNT 查询。拿上面的例子来说，需要统计满足 WHERE status = 1 的全部记录数：

SELECT COUNT(*) FROM user WHERE status = 1;

COUNT 看似简单，但有个隐蔽的性能问题：如果表数据量大，COUNT(*) 即使走了索引也可能需要扫描大量数据。常见的优化手段是给过滤字段建合适的索引，让 COUNT 走覆盖索引；如果是超宽表，也可以用专门的计数表或缓存来扛，但这属于后话了。

总页数的计算也有讲究，推荐用整数运算避免浮点误差：totalPages = (total + pageSize - 1) / pageSize。例如 total=356、pageSize=20，代入公式是 (356 + 19) / 20 = 375 / 20 = 18，整除得 18 页。这里用到了一个小技巧：分子加 pageSize-1 再整除，等价于向上取整，比先除再调用 ceil 函数更稳，也省一次类型转换。

3.4 排序稳定性：分页最容易忽略的隐藏条件

如果说 offset 算错是显性 bug，那么排序不稳定就是隐性 bug。什么是排序不稳定？就是 ORDER BY 的字段在结果集里存在大量重复值，例如只按 created_at 排序，而同一秒内创建了 1000 条记录。MySQL 对相同排序值的返回顺序是不保证的，这就导致翻页时同一条数据可能出现在上一页末尾，也可能出现在下一页开头，用户看到的现象就是"数据重复"或者"数据缺失"。

解决方法是给排序条件加一个绝对唯一的次要字段，最常见的就是把主键 id 作为第二排序键：

SELECT id, name, created_at FROM user WHERE status = 1 ORDER BY created_at DESC, id DESC LIMIT 20 OFFSET 40;

这个 id 就是一个"稳定锚"，它保证了即使主排序字段重复，整条排序序列也是确定性的，翻页结果才会稳定。这个细节我在代码评审时几乎每次都会提醒，因为它不会让接口报错，只会让数据在特定场景下"看起来不对"，属于最磨人的那类问题。

4. 性能优化：当 PageIndex 从 1 翻到 10 万页之后

4.1 OFFSET 深分页为什么这么慢

很多项目的分页在数据量小时毫无感觉，但数据量到了百万级，你翻到第 10 万页就会发现接口响应时间从几十毫秒飙到几秒甚至十几秒。问题就出在 OFFSET 的语义上。

用生活化的类比：OFFSET 分页就像在一条长长的队伍里从队头开始数人，每次要走到第 2 万人那里，你都得从第一个人数起。数据库为了返回第 10 万页的数据，必须先扫描并丢弃前 199 万条记录，这个"丢弃"不是免费的，它占用磁盘 IO、占用内存、占用排序时间。越到后面，OFFSET 越大，扫描的无效数据越多，速度呈线性甚至超线性下降。

我在一个报表项目里实测过，一张 300 万行的订单表，按 OFFSET 分页，前 100 页响应都在 100 毫秒以内，但翻到第 5 万页后，单次查询耗时接近 8 秒，整个列表功能基本不可用。这时候再想靠加索引去救 OFFSET，效果已经非常有限了，因为瓶颈不在单行查询，而在大量无效行的"跳过"过程。

4.2 游标分页：不靠页码的另一个思路

深分页的治本方案之一，是抛弃页码，改用游标分页，也就是很多人说的 keyset pagination 或者 cursor-based pagination。它的核心思路不是"跳过 N 条"，而是"从上次结束的位置继续往后找"。

以按 id 排序为例，前端每次请求时把上一页最后一条记录的 id 作为游标传入，后端这样查：

SELECT id, name, created_at FROM user WHERE status = 1 AND id > #{lastId} ORDER BY id ASC LIMIT 20;

这样做的好处非常直观：查询直接通过索引命中 id > lastId 的范围，扫描的永远是 20 条左右的数据，分页深度对性能几乎没有影响。哪怕翻到第 100 万条，耗时也跟翻第一页差不多。代价是前端页码条没法直接跳到任意页了，只能"上一页/下一页"这样线性翻，这对大部分 C 端场景（信息流、评论列表）完全够用，但对后台管理系统那种需要精确跳页的场景就不合适。

另一个游标分页的进阶用法是复合游标，比如按 (created_at, id) 排序，游标携带这两个值，WHERE 条件写成：

WHERE (created_at, id) < (#{lastCreatedAt}, #{lastId})

这是 PostgreSQL 和 MySQL 都支持的元组比较语法，可以稳定实现多字段排序的游标分页。不过复杂度会稍微上去一点，我建议先在简单场景落地，再逐步推广。

4.3 索引设计和热点缓存

无论用 OFFSET 还是游标分页，索引都是分页查询绕不开的地基。给分页查询设计索引时，核心原则是"让 WHERE 过滤和 ORDER BY 排序都能命中同一个索引"，避免出现排序临时文件。例如查询条件是 status=1 且按 created_at DESC 排序，那么一个 (status, created_at) 的复合索引就比 status 单独建索引高效得多。

再配合覆盖索引，也就是 SELECT 需要的字段都包含在索引里，查询可以直接从索引返回结果，连回表都省了，这在高频分页接口上是肉眼可见的优化。

对于首页、第二页这种访问量极高的分页数据，缓存也是一个思路。很多系统的流量分配极不均匀，前几页占了绝大部分访问。我实践过的做法是给前 3 页的查询结果做短时缓存，TTL 设置为 30 秒到 1 分钟，配合数据库变更后的主动失效，能把列表接口的 TP99 大幅降下来。但缓存一定要注意两点：一是数据一致性要求高的场景不能用；二是缓存 key 必须包含完整的查询条件、排序条件和分页参数，否则就串页了。

5. 常见问题与排查实录

5.1 历年攒下来的 PageIndex 问题速查表

我把这些年碰到过的分页问题整理成了一个速查表，方便大家直接对照排查。

5.2 三个让我排查到深夜的真实案例

第一个案例是排序重复导致的数据串页。那是一个帖子列表，ORDER BY updated_at DESC，但数据库表的 updated_at 精确到秒，同一秒内有多条帖子被更新时，MySQL 的返回顺序就飘了。用户反馈"刷新几次后第二页出现了一条刚刚在第一页看过的帖子"。我一开始怀疑是缓存问题，查了半天才发现是排序稳定性。最后把 ORDER BY 改成 updated_at DESC, id DESC 后问题消失。

第二个案例是 pageSize 超限导致的接口超时。有个活动页面通过 URL 上的 ?pageSize=5000 访问，前端没有限制，后端也没校验，一次拉几千条数据还把深分页的 OFFSET 算得很大，数据库直接扛不住。从那以后我把所有列表接口的 pageSize 都加了 le=100 的硬上限，超限宁可直接拒绝，也不无脑返回。这个教训说起来简单，但线上每个看似正常的参数背后都可能藏着非预期的调用方。

第三个案例是前端和后端页码语义不一致引发的线上事故。前端用的组件库从 1 开始，后端某次重构换成了从 0 开始的框架，结果所有列表第一页都是空的。当时排查了很久，最后是抓包对比前端入参和后端日志才定位到"差一页"的问题。现在我在接口文档里会对每一处页码参数标注"起始值：1"，并在后端入口统一做语义转换，这类问题就很少再发生了。

5.3 代码评审时的分页验收清单

我在团队里做代码评审时，对分页接口有一个固定的检查清单：入参是否有 pageIndex 和 pageSize 的边界校验；返回值是否包含 total；SQL 的 WHERE 条件和 COUNT 是否完全一致；排序条件是否包含唯一性锚点字段；pageSize 是否设了上限；深分页是否有保护策略；如果用的 OFFSET 分页，是否评估过数据量增长后的风险。

这套清单看起来琐碎，但每一条背后都对应着一次线上问题或者用户投诉。分页是整个系统里最不起眼、却最容易被"看起来没问题"骗过的地方，越早把这些规则固化到流程里，后面就越省心。

我个人实际做项目时还有一个习惯：写完列表接口先不改代码，直接模拟翻前几页、翻最后一页、翻到超范围页码、修改 pageSize 到边界值这四种情况，都验证一遍再交付联调。这四步走完，分页相关的低级 bug 基本能消灭掉七成以上。分页这东西，说简单是真简单，说复杂也真复杂，关键在于你是否愿意在每个边界条件上都多问一句"如果传这个值会怎么样"。养成这个习惯之后，你会发现 PageIndex 不再是那个总让你踩坑的变量，而是一个可以被精确掌控的、值得信任的小伙伴。