企业官网建设流程全解析

1. 先搞明白 PageIndex 到底是什么：它和“第几页”永远差着 1

做分页需求时，不管你是前端写表格还是后端写接口，几乎都会碰见 PageIndex 这个词。但很多项目的 Bug 恰恰就出在这个词上：大家嘴上说的 PageIndex，其实就是“第几页”，于是前端传 pageIndex=3 表示第三页，后端拿到 3 也直接当第三页处理，最后数据却是从第 31 条开始取的，因为偏移量被人为加了一次 1。更常见的情况是，页面显示“第 3 页”，前端组件内部是 current=2，接口参数却是 page=3，三条代码三个理解，第一轮联调就吵起来了。

想说清楚 PageIndex，得先接受一个反直觉的设定：PageIndex 是页码的索引，不是页码本身。它真正对应的概念是数组下标。数组第一个元素下标是 0，所以第一页的 PageIndex 也是 0；用户眼里看到的第一页叫“第 1 页”，那是显示层把索引加 1 之后的结果。你完全可以不用 PageIndex，直接叫 pageNumber 并且从 1 开始数，很多框架也确实这么干，但关键是整条链路必须同时采用同一个基准，不能前端按 0 算、后端按 1 算、SQL 又按显示页码算。

为什么计算机世界偏爱 0 起点？因为分页本质上是“从有序数据集合里截取一个切片”，切片的位置就该用下标来表达。第一页实际上是从第 0 条记录开始取前 N 条，第二页是从第 N 条开始取 N 条。如果坚持用 1 起点的页码，那每次截取前都得做一次“页码减 1”的换算；如果某处代码忘了减，线上就查不到第一页数据。一次两次可以靠人肉提醒，几十个接口下来基本必炸。

另外，不同框架对这个参数的叫法也很不统一。前端组件常叫 currentPage、current、activePage；后端接口文档里可能叫 page、pageNo、pageNum、pageIndex；数据库方言里则是 offset、start、skip。名字怎么取倒不是致命伤，致命的是同一个项目里，这些名字指向的语义彼此矛盾。

我在项目里定的规矩就一句话：所有接口统一接收 pageIndex + pageSize，pageIndex 从 0 起算；进入 Service 层之前必须先把各种来源的页码折算成这个基准。谁要是图省事新起个 page 参数并且从 1 开始，代码评审直接打回。这不是固执，是在给整条数据链路减少一个全局都要做的“减 1”动作。

2. 一次线上翻页翻崩的事故复盘：PageIndex 的边界问题

聊完定义，来复盘一个我实际接手过的线上事故。那是一个带搜索筛选的后台列表页，数据量不大，总共 50 条记录，每页 10 条，正常翻页完全没问题。用户操作路径是这样的：先翻到第 5 页，然后在搜索框里输入一个关键字重新查询，点击“搜索”按钮，页面直接白屏。监控里能看到接口报了 500，错误日志指向一段分页计算代码，抛出的是数组越界异常。

2.1 事故是怎么一步一步暴露的

第一次复现时，我开着浏览器 F12 盯着 Network 面板，完整操作链路是这样的：

1. 列表初始化，pageIndex=0，pageSize=10，接口返回 total=50，maxPageIndex=4。
2. 用户连续点了 4 次“下一页”，页面上的 currentPage 停留在 5（前端内部值是 4）。
3. 用户在搜索框输入新关键字，触发重新查询。
4. 前端把 currentPage=4 原封不动地带进查询请求，传给后端 pageIndex=4。
5. 新查询条件下 total 只有 3 条，maxPageIndex 应该是 0，但后端拿着 pageIndex=4 去做切片。

第 5 步在数据库层面不一定立刻报错，因为 offset 超出范围时很多数据库只是返回空结果，不会主动抛异常；但我的代码里在切片后又对结果数组做了“取第一条做默认展开”的操作，空数组取下标 1 之类的地方就炸了。这一炸，直接把 500 甩到用户脸上。

2.2 根因：数据总量变了，页码状态却没跟着变

这个事故的根子不在数据库，也不在异常处理，而在前端页码状态和后端数据总量之间失去了同步。用户在搜索前，页码状态是 4，这个状态是依据旧数据总量（50 条）算出来的；搜索后总量变成了 3 条，页码状态还是 4，这时候 4 这个值已经没有任何意义了。

但问题不止于此。再往下挖，后端也没有做防护。接口收到 pageIndex=4，第一反应应该是校验这个值在当前数据总量下是否合法，而不是直接拿过去切片。如果在 Service 层做一个“页码越界自动收缩”的动作，把越界的 4 收缩为 maxPageIndex（0），这次事故根本不会发生。

我后来把这类问题总结成一个通用场景：只要用户操作改变数据总量，页码就必须重置或者被后端温和地纠正。数据总量发生变化的操作包括但不限于：搜索、筛选、切换分类、删除记录、批量导入后刷新列表。这些操作之后，前端最好把页码重置为 0；如果产品要求保留页码，那后端至少要能钳制越界值。

2.3 三个最容易翻车的数据总量边界

除了上面说的“搜索后页码越界”，还有三个边界场景，我在不同项目里轮番遇到：

• 数据量为 0：total=0 时，maxPageIndex 算出来是负数，如果直接用 Math.ceil(0 / pageSize) - 1，结果是 -1，PageIndex 会被钳成负数或者直接把分页组件搞崩。
• 数据量正好是整数页：50 条数据每页 10 条，maxPageIndex=4，用户在第 5 页删掉 10 条记录后，总量变成 40，maxPageIndex 变成 3，但当前页面还停留在 4。
• 数据量刚好为 1：total=1，pageSize=10，maxPageIndex=0，看起来没问题，但如果分页组件因为某种原因把 current 初始化成 1，就会出现第一页就报错的可笑场景。

这几种情况，本质上都指向同一个防御动作：不管页面怎么跳，后端必须保证最终执行的 pageIndex 落在 [0, maxPageIndex] 区间内；maxPageIndex 必须用Math.max(0, ...)兜底，不允许出现负数。

3. PageIndex 从 UI 走到 SQL：一条链路，三处各自为政的“页码”

分页查询这条链路上有三层，各层眼里的“页码”不完全一样。前端组件里维护的是 currentPage，接口参数里写的是 pageIndex，数据库执行的却是 OFFSET。这三者如果各算各的，联调就是一场灾难。

3.1 前端组件：负责把用户看到的页码翻译成 PageIndex

前端分页组件通常会暴露两个东西：当前页码 current 和切换页码的回调。用户点击“第 5 页”按钮时，组件回调给出的可能是 4（如果你设置成 0 起点）也可能是 5（组件内部默认 1 起点）。这个差异必须在组件配置阶段就统一，不要写“点击事件里把值减 1”这种补丁。

我的习惯是让分页组件直接工作在 PageIndex 上。也就是说，组件显示的页码是“第 N 页”，但内部变量和对外回调值都保持 N-1，显示层做一次格式化即可。这样前端组件和接口参数之间没有任何换算，最大的好处是少一个转换点就少一个出错点。但凡你用过“前端传 page=5，后端减 1 变 4，SQL 再乘 pageSize”这套流程，早晚会在某个页面发现第二页数据是重复的第一页数据，那就是有人漏了减 1。

发送请求时还有个细节容易踩坑：pageIndex 和 pageSize 要用数字类型传，不要用字符串拼接。曾经见过同事写出pageIndex=${current + ''}这种代码，虽然大多数后端能自动转型，但只要配合上一些严格的类型校验框架，请求直接 400。更隐蔽的是，如果中间有一层网关或者 WAF 对参数做了字符串解析，数值型参数被转成字符串后又丢失前导空格，问题就变得极其难排查。

3.2 后端接口：收到 PageIndex 以后要过的三关

后端是整条链路的核心，接口接收到的 pageIndex 必须经过三关才能放行：

第一关，类型与格式校验。pageIndex 必须是整数，不能是小数、负数、字符串或者 null。负数的意义本身就很含糊，到底是“从后往前数”还是“非法请求”？直接拒绝才是干净的做法。

第二关，上限校验。pageSize 必须有最大值，我一般限制在 200，防止用户一次拉走全表数据，也防止有人拿这个参数做压测。pageSize 不合法时直接返回参数错误，不静默替换。

第三关，越界钳制。pageIndex 超过 maxPageIndex 时，可以和前端约定好策略：返回空数据但附带正确的 maxPageIndex，或者自动收缩到最后一页。我更推荐自动收缩，因为前端拿到缩回来的数据后，可以根据返回的 pageIndex 修正自己的页码状态，用户体验更平滑。

这三关在实现上有讲究，重点在于校验逻辑应该放在 Service 层，而不是 Controller 层。原因很简单：Controller 往往只管参数接收和返回封装，而分页计算需要知道 total 才能算 maxPageIndex，这个信息在 Service 层才能拿全。如果强制Controller 先查一次 total 再做校验，等于一个请求打两次数据库，完全没有必要。

3.3 数据库查询：真正截取数据的只有 OFFSET 和 LIMIT

到了数据库这一层，已经不存在“第几页”的概念了，只有两个数字：从第几行开始（OFFSET）、取多少行（LIMIT）。无论前端传的是 pageIndex 也好，pageNumber 也好，最终拼进 SQL 的一定是偏移量：

SELECT id, title, created_at FROM articles ORDER BY id DESC LIMIT #{pageSize} OFFSET #{pageIndex * pageSize};

这里的乘法操作建议显式地写在参数构造处，而不是在 SQL 里做表达式运算。你可能会看到有人写OFFSET #{pageIndex} * #{pageSize}，虽然 MySQL 大多数情况下能算出正确结果，但遇到一些参数化查询框架的预编译模式时，表达式被当作字符串值绑定到参数上，就会得到一个字面上的 “0 * 10” 字符串，轻则语法报错，重则产生不可思议的查询结果。

还有一点：分页查询一定要搭配稳定排序，否则 OFFSET 分页在并发写入下会出现重复或漏数据。我见过有人偷懒不写 ORDER BY，数据库默认存储顺序一变化，第二页和第一页的数据就重叠了。入门开发踩这个坑的特别多，看起来是 PageIndex 配置问题，实际上是排序不稳定导致的。

4. 把 PageIndex 封装成一套可复用的分页逻辑：我的落地写法

前面讲了原理和踩坑，这节给出一套我在实际项目里反复使用的封装方案。它不是一个完整框架，而是一种组织代码的套路，换语言换框架都能照搬。

4.1 先做参数校验和规整，再进业务代码

所有分页相关的方法，入口第一步就是调用一个规整函数，把外部传入的原始参数变成合法的内部值。这段代码的核心逻辑是“先兜底、后钳制”：

function normalizePageIndex(rawIndex: number | string, total: number, pageSize: number): number { let index = Number(rawIndex); // 非法输入一律回到第一页 if (!Number.isInteger(index)) { index = 0; } // 总页数为 0 时，maxPageIndex 至少是 0，不允许出现负数 const maxPageIndex = Math.max(0, Math.ceil(total / pageSize) - 1); // 双向钳制 return Math.min(Math.max(index, 0), maxPageIndex); }

规整函数做完后，业务代码里永远只能出现处于合法区间的 pageIndex。这样写的最大好处是：数据库查询、缓存Key 拼接、日志记录，所有下游模块拿到的 PageIndex 都是可信的。预算式防御不会再被奇怪的脏数据传染。

用这套规整函数处理上面事故里的场景：total=3，pageSize=10，maxPageIndex=0，传入 pageIndex=4，输出是 0，查询不会越界，前端收到的响应里也带着 pageIndex=0，页面显示第一页，整个过程对用户是平滑的。

4.2 分页响应的标准结构：为什么必须带上 maxPageIndex

我维护的分页接口，响应体结构严格统一为下面这个样子：

{ "pageIndex": 0, "pageSize": 10, "total": 50, "maxPageIndex": 4, "records": [] }

很多接口只返回 total 和 records，不返回 maxPageIndex，这个信息缺失会导致前端必须自己算总页数。前端自己算不是不行，但一旦 total 是后端计算口径算出来的，而前端用了一个不同的除法方式或取整逻辑，页码按钮数量就会对不上。把 maxPageIndex 交还给后端来算，等于把“一共有多少页”这个事实的权威定义收拢到了数据源头。

同样要多说一句：当 total=0 时，maxPageIndex 必须是 0，哪怕你认为“没有数据就没有页数”。前端通常需要根据 maxPageIndex 决定是否展示空态文案，如果一个空列表返回的是 total=0、maxPageIndex=-1，分页组件的“上一页/下一页”按钮状态就会错乱。所以我上面规整函数里特意用了Math.max(0, ...)把负数兜住。

4.3 封装边界：该放在 service 层，而不是 controller 层

整套封装放进哪个层，直接决定了它会不会被绕过。最理想的位置是 Service 层统一封装，Controller 只做 Web 适配。如果放 Controller 层，那 Service 层内部别的方法如果直接接收了 pageIndex 且没做规整，危险仍然存在。

我实际项目里的分层习惯是：

1. Controller 层接收 HTTP 参数，只做类型转换，不写任何分页计算。
2. Service 层入口调用normalizePageIndex，随后才查询 total 并执行列表查询。
3. DAO/Mapper 层只接收 offset 和 limit，不感知 PageIndex 的存在。

这个分层的用意是把“分页”这个横切关注点收敛到 Service 层，保证任何调用方——包括内部定时任务、消息队列消费者——在调用分页方法时都必须经过同一套校验。有一个月我排查一个后台任务翻页报错，最后发现是任务代码直接跳过了 Service 层，拿着原始 pageIndex 就去查库，绕过了保护。这正好说明规范只能锁住守规矩的调用方，锁不住入口设计本身。

封装里还应该包含一个默认值常量：pageSize 默认 10，最大 200。这两个值不要散落在各个方法里。很多接口一开始只用默认值，后来产品要支持每页 500 条，开发反手就在 XML 里写了个 500，结果线上查询直接超时。把常量统一放在一个分页配置类里，后续调整只是一处改动。

5. 生产环境里的防呆措施与排错小技巧

框架搭好了，代码封装也落地了，但要保证一个团队长期不重新踩进 PageIndex 的坑，靠的是约定和排查手段。

5.1 约定优先：接口文档里必须写清楚基准

所有分页接口的文档里，我规定必须有一句话：“pageIndex 从 0 开始，第一页为 0；pageSize 为每页条数，上限 200。”同时给出一组示例请求和响应。这句话看似多余，实际是在划清责任的边界。

凡是文档里没写基准的接口，前端只能靠猜；写代码的人靠猜，联调期就会互相甩锅。与其让两拨人争一整天，不如在文档里用一个示例钉死。我还见过一些团队用page=1代表第一页，这也不算错，但务必在内部翻译成 PageIndex 时统一用 0 基准，不要图方便直接把 1 传下去。任何人的记忆都会在半夜被一个“这个接口不太一样”的接口骗过。

5.2 空数据时的 PageIndex 陷阱

生产环境里，列表页最容易被忽略的用例就是空数据。这里说的空数据不是 total=0 这一种，还包括搜索条件组合后 total=0、删光数据后 total=0、以及导入失败后列表为空。

在这类场景下，PageIndex 不一定是 0。比如用户本来在第 3 页，之后把列表里所有记录都删了，前端还停留在第 3 页，此时发请求带 pageIndex=2，total=0。别小看这种场景，很多后端在 total=0 时返回空 records，前端拿到空数组后不知道要不要重置页码，页面会停在“空白的分页条”上。

我推荐的做法：total=0 时，服务端应返回 pageIndex=0 和 maxPageIndex=0，并且响应里的 records 为空数组而不是 null。前端分页组件依据响应里的 pageIndex 自修正当前页。如果响应里没有 pageIndex，前端必须自己判断“records 为空时强制跳回第 1 页”，虽然能做，但这本质上是把后端该管的事推给了前端。

5.3 排错三板斧：四个变量定位问题

最后分享一个排查分页 bug 的实用方法。遇到分页表现异常——翻页数据重复、漏数据、页码按钮数量不对——先不要在代码里到处打断点，直接在接口日志里打印四个变量：pageIndex、pageSize、total、maxPageIndex。绝大多数问题一眼就能定位：

这四个变量如果打印出来全对，那问题大概率出在数据库排序、缓存或并发写入上，跟 PageIndex 本身无关，这时候再把排查方向切换到 SQL 执行计划和缓存策略。

我在实际项目中有一段时间把这条打标语做成了一行结构化日志，每次分页查询都记录 rawIndex、normalizedIndex、offset、limit、total，配合 traceId 串起整条调用链。后来团队新来的开发遇到分页怪问题，第一反应不是翻源码，而是先去日志里捞这五个字段，效率提升非常明显。分页本身不是复杂技术，但它是所有列表页的公共底座，底座一旦不稳，上面盖多少业务都晃。把这套约定和防呆处理沉淀下来，比反复救火有用得多。