企业官网建设流程全解析

PageIndex这个词，我在日常代码评审里见过太多版本。有人把它当“第几页”，有人把它当“页码”，还有人把它和PageNumber混着用，结果接口文档里写的pageIndex=1，前端实际传的是第2页。我刚工作那会儿也因为这个闹过笑话：列表一共7页，我在前端把当前页设成7，结果切到第8页，后端返回一个空数组，我对着接口文档看了半天才发现，两边的起点根本不在一个坐标系里。

这篇文章想把PageIndex这件事彻底说清楚。它不只是一个变量名，而是分页体系里“第几页”这个语义在后端、前端、数据库三层之间传递时，最容易出问题的一个环节。什么场景会用到？几乎所有需要展示列表的功能——订单列表、用户列表、日志列表、商品列表——都离不开它。适合谁看？刚开始写分页接口的新手，以及被“翻页翻到一半数据乱掉”折磨过的老手。我会从定义讲起，一路聊到SQL、前端组件、数据一致性、深分页陷阱，最后给一份可以直接照着排查问题的笔记。

1. 分页场景中的PageIndex到底在表达什么

1.1 从一张报价单列表说起

去年我给内部系统做一张报价单管理页，需求看起来非常简单：列表按创建时间倒序排列，一页显示20条，底部有页码按钮，可以随便翻。开发第一天我就把接口写完了，大概长这样：

GET /api/quotations?pageIndex=1&pageSize=20

当时觉得很简单：pageIndex等于当前页号，第二页传2，第三页传3，再正常不过。结果联调的时候，前端同事拿着同一个接口来问我：“我点击第2页，你返回的还是第一页的数据，是不是你SQL写错了？”

我查了半天，最后发现问题出在一个约定上：前端组件（Element UI的el-pagination）默认页码从1开始，但它把当前页存成了currentPage；我在后端定义pageIndex时，却默认它从0开始——第一页是0，第二页是1。前端点击“2”传给我，我按“第三页”去查了，自然会错位。

这件事之后我养成了一个习惯：无论参数名叫什么，先约定起点，再谈别的。命名本身不是问题，问题在于同一份代码里没有统一语义。

1.2 PageIndex、PageNumber、CurrentPage，为什么大家叫法不一

同一份需求里，不同角色的命名偏好完全不同：

• 用户视角：看的是第1页、第2页、第3页，从1开始。
• 前端框架视角：知名组件大多把当前页命名成currentPage或current，而且从1开始，比如Ant Design的Pagination.current、Vue生态里el-pagination的current-page。
• 后端与部分底层框架视角：很多后端语言和框架习惯从0开始索引。ASP.NET的GridView里自带PageIndex属性，第一页就是0；很多接口定义里也沿用这个习惯。

这样一来就出现了同名不同意的混乱场面。有的项目里，PageIndex是用户认知的页码（从1开始）；有的项目里，它是数组索引（从0开始）。如果项目文档没有明确写清楚，几乎注定会踩坑。

我的建议是，在接口文档里把三者关系写死：

1.3 前后端视角下PageIndex的职责划分

分页流程里，每个角色只负责一部分：

• 前端负责：把用户点击的页码，通过请求参数传给服务端，并展示后端返回的total、totalPages、list。
• 后端负责：解析pageIndex和pageSize，做参数校验，计算偏移量，执行查询，返回当前页数据与总数。
• 数据库负责：根据LIMIT/OFFSET（或OFFSET/FETCH）截取数据行。

这三层如果不统一，最常见的问题就是“前端页码从1开始，后端索引从0开始”，少传了一个-1。所以在我现在的团队里，接口统一约定pageIndex从0开始（因为后端计算偏移量时最顺手，offset = pageIndex * pageSize），前端在传参前统一执行pageIndex = currentPage - 1。这个转换放在一个公共请求封装里，谁都不许在业务代码里裸写。

注意：这并不意味着从0开始是唯一正确答案，它只是我在多项目实践后觉得最容易收敛的约定。如果你的团队已经把pageIndex定义为从1开始，也没问题，前提是所有人都知道这个定义，并且后端计算偏移量时主动减一。

2. 起点之争：第0页还是第1页，背后是计算模型的差异

2.1 为什么会有从0开始的设计

从0开始并不是为了刁难人，而是因为计算机里的“索引”天然从0起步。假设一页10条，第一页的数据从第0条到第9条，第二页从第10条到第19条。如果你用“用户页码”去算偏移量，公式得写成：

offset = (pageNumber - 1) * pageSize

从0开始的pageIndex则可以直接用：

offset = pageIndex * pageSize

后者少了一次减一操作，看起来微不足道，但是在大量接口里统一约定后，就避免了“要不要减一”的各种分支判断。很多后端框架，比如Java的PageHelper、ASP.NET Core的分页封装，内部也是这么算的。

2.2 边界计算：offset、pageSize与totalPages

分页系统里，真正关键的计算就三个：

• 偏移量：offset = pageIndex * pageSize
• 总页数：totalPages = Math.ceil(total / pageSize)
• 当前页条数：list.size()（小于等于pageSize）

举个例子。总数total = 357，pageSize = 20，则总页数：

totalPages = Math.ceil(357 / 20) = Math.ceil(17.85) = 18

pageIndex合法范围是0到17。如果接口收到18，说明越界了，需要处理。这里有个常见错误：有的同学用total / pageSize，得到17，然后前端最后一页显示到17页，实际上有357条数据，第17页（用户视角第18页）还有17条数据，但前端只渲染了17页的页码，等于永远看不到最后的17条数据。

Math.ceil这个函数看着不起眼，却是分页正确性的关键。换成Math.floor会丢数据，用整数除法在部分语言里会直接截断，连小数都没有。我见过不止一次因为totalPages算错，前端在最尾页渲染出“暂无数据”的案例。

2.3 越界、负值、空页，防御逻辑要写在哪儿

生产环境里，用户真的会翻到已经因为删除而消失的最后一页，真的会有爬虫拿负数页码来探测，也会有人传一个pageSize=1000000想一次性拖走全表。后端必须对这些不合法输入做防御。

我常用的校验策略：

• pageIndex < 0：直接返回第一页数据，或者返回参数错误，看产品需求。但绝对不要让SQL的OFFSET为负数，不然数据库直接报错。
• pageSize > 200：强制截断为200。这个上限需要根据业务场景评估，比如导出类接口可能需要更大，但列表查询200已经足够。
• pageIndex超过总页数：两种处理，一种是返回空页，让前端把页码重置；一种是把最后一页的数据原样返回。我一般倾向于后者——用户已经看到了第50页，哪怕数据只剩20页，直接把最后一页给他，体验也比“无数据”好。

防御逻辑放在后端还有一个好处：不是所有前端都能被你约束。小程序、App、第三方接口调用方，甚至监控脚本，都可能绕过你的前端组件直接请求接口。依赖前端把参数做对，远不如后端自己兜住底。

3. 实操：从零实现一个标准化分页接口

3.1 接口契约：参数与返回结构

我一般把响应体封装成统一结构：

{ "code": 0, "message": "ok", "data": { "list": [...], "total": 357, "pageIndex": 0, "pageSize": 20, "totalPages": 18 } }

这里有个细节：返回体里的pageIndex，是服务端实际查询用的页码，而不是前端传来的原始值。这么做的好处是，调试时前端看到返回的pageIndex=0，就能对照出自己传的参数到底被服务端怎么解释了。有些项目还会带上hasMore布尔值，给移动端“上拉加载更多”用，减少一次前端计算。

3.2 SQL写法：不只有LIMIT和OFFSET

数据库查询是分页的落地点。不同数据库写法有差异：

MySQL：

SELECT id, order_no, amount, created_at FROM quotation ORDER BY created_at DESC, id DESC LIMIT 20 OFFSET 0;

等价写法是LIMIT 0, 20，但可读性差一些，我更喜欢显式写OFFSET。PostgreSQL、SQL Server、Oracle 12c以上支持标准写法：

SELECT id, order_no, amount, created_at FROM quotation ORDER BY created_at DESC, id DESC OFFSET 0 ROWS FETCH NEXT 20 ROWS ONLY;

注意ORDER BY一定要有。没有稳定排序的分页，翻几次页数据就错乱了，后面排障部分再细说。

3.3 后端实现：Spring Boot示例

控制器接收参数并调服务：

@GetMapping("/api/quotations") public Result<PagedResult<QuotationDTO>> list( @RequestParam(defaultValue = "0") int pageIndex, @RequestParam(defaultValue = "20") int pageSize) { // 防御：pageSize 最大 200 pageSize = Math.min(pageSize, 200); pageIndex = Math.max(pageIndex, 0); return Result.success(quotationService.pageQuery(pageIndex, pageSize)); }

Service层计算offset并统计总数：

public PagedResult<QuotationDTO> pageQuery(int pageIndex, int pageSize) { int offset = pageIndex * pageSize; List<QuotationDTO> list = quotationMapper.pageQuery(offset, pageSize); long total = quotationMapper.countByCondition(); int totalPages = (int) Math.ceil((double) total / pageSize); return new PagedResult<>(list, total, pageIndex, pageSize, totalPages); }

OFFSET计算放在Service层而不是SQL里，原因是可读性更好、便于全局调试。这里有一个容易被忽略的点：分页接口至少要执行两条SQL——一条查数据，一条查总数。如果这两条SQL之间有人插入了数据或删除了数据，总数的准确性会略有偏差。大部分业务场景可以接受，金融、库存类的场景必须考虑事务隔离级别，必要时在同一个事务里执行。

3.4 前端对接：Vue + Element Plus的实际代码

前端的要点是：组件里看到的页码（current-page）从1开始，传给后端的pageIndex从0开始。封装在request层里统一处理：

// api/request.js function buildPaginationParams(pageNo, pageSize, fromOneStart = true) { return { pageIndex: fromOneStart ? pageNo - 1 : pageNo, pageSize } }

页面里的分页组件绑定：

<el-pagination v-model:current-page="currentPage" :page-size="queryParams.pageSize" :total="total" layout="total, prev, pager, next" @current-change="fetchList" />

点击页码时，currentPage已经是用户页码，比如第5页。请求里传的pageIndex则是4。这个“减一”藏在请求封装里，前端组件和后端接口各安其职，谁也不需要猜测对方。如果要对接Ant Design，逻辑一样：Pagination的current属性也是从1开始，传给后端时同样减一。

3.5 总数统计的两种姿势：COUNT(*)和近似估算

总数统计是小细节，但也是性能隐患。数据量小时直接COUNT(*)没问题，几百万行之后，每次都精确COUNT很浪费。很多系统采用“近似总数”策略：先查一遍总数再缓存，过期时间几秒甚至几分钟。这样尾页可能不是最新状态，但换来的是列表查询接口的稳定响应时间。

如果业务必须精确，可以考虑把总数维护在统计数据表里，或者对高频筛选条件建覆盖索引。ORDER BY created_at DESC, id DESC这两个字段的组合索引，对避免分页查询的Using filesort意义很大，这在深翻页时尤其明显。

3.6 实操心得：写分页接口时最容易漏的三件事

第一件，返回给前端的总数total，必须是Long而不是Integer。列表量稍微一上来，Integer溢出不是吓唬人。第二件，排序字段和分页字段一定要出现在索引里，否则翻页越深越慢。第三件，接口文档里必须写清pageIndex起点，甚至可以加上一句示例：“第一页pageIndex=0，第二页pageIndex=1”。目前我的接口文档模板里这句话是标配。倒不是逼所有人记忆API，而是给三个月后接手维护的同事留一条活路。

4. 大数据量下的PageIndex困境与替代方案

4.1 深分页：OFFSET过大的性能灾难

OFFSET 200000这种查询，在MySQL里意味着数据库要扫描前20万行，然后丢弃，只返回后面的20条。页码越深，扫描越慢。有一个很经典的场景：管理后台导出日志时，用户直接把分页页码拖到第100000页，接口直接返回超时。

我见过最夸张的一次，一个订单列表接口，pageIndex=500000时，慢查询日志里这条SQL跑了8秒。原因就是OFFSET太大了。解决思路有三个：限制最大页码、改用游标分页、优化ORDER BY索引。多数场景下，光限制最大页码就能避免80%的问题——真的没人需要翻到第50万页看历史订单。

如果业务上有“跳页”需要，建议把pageIndex上限设成比如1000，超过就提示“数据量过大，请使用搜索或筛选条件”。这个限制可以放在后端，也可以放在前端，但后端必须兜底。

4.2 游标分页：放弃页码，用排序键定位

游标分页（也叫键集分页、Seek Method）的逻辑是：不用页码，而是用“上一页最后一条数据的某个字段”来定位下一页。比如按id倒序分页，下一页就是：

SELECT * FROM quotation WHERE id < ? ORDER BY id DESC LIMIT 20;

这里的?就是上一页最后一条的id，由前端回传给接口，常见叫法是cursor、nextToken或lastId。

这种方式的优点是：即使数据在翻页间隙发生了变化，也不会跳过或重复；深翻页性能恒定，因为数据库能利用主键索引直接定位。缺点是用户看不到总页码，不适合“跳到第50页”的场景。所以适合“加载更多”式的列表，比如内容流、聊天记录、活动动态。

4.3 延迟关联：深分页查询的保底手段

如果业务上确实需要页码分页，又担心深分页性能，可以用延迟关联（Deferred Join）优化：

SELECT q.* FROM quotation q INNER JOIN ( SELECT id FROM quotation ORDER BY created_at DESC, id DESC LIMIT 20 OFFSET 200000 ) tmp ON q.id = tmp.id ORDER BY q.created_at DESC, q.id DESC;

子查询先在索引上执行偏移，只取出20个主键，再回到主表拿完整行。相比直接大OFFSET，这套写法能大幅减少回表和扫描行数，在MySQL上效果尤其明显。不过它也没能完全规避OFFSET的扫描成本，只是把压力从全行数据缩小到了索引字段。

4.4 什么场景下应该坚持用PageIndex

说了这么多替代方案，但PageIndex并没有死。后台管理系统、报表系统、表格型数据列表，用户明确需要“跳到第N页”和“总页数”，这类场景用页码分页是最直观的。PageIndex适合数据量在几十万到几百万级别、排序稳定、且业务上允许一定查询成本的场景。真到千万级以上或者频繁深翻页，再考虑游标、分区、或者搜索引擎方案。

另外提一句：数据库领域也有“索引页”的概念，叫Index Page，是B+树组织索引时一个物理页面的单位。它和Web分页的PageIndex不是一回事。但两者有个共同点：都强调“定位”。一个定位数据页上的记录，一个定位数据集里的某一页。理解了这个底层逻辑，再看各种分页方案的取舍，就清楚多了。

5. 分页排查手册：常见问题与踩坑实录

5.1 翻到第3页数据突然变空

现象：用户正常浏览列表，翻到第3页，页面空白或者提示暂无数据。排查顺序一般是：

1. 打开浏览器Network面板，看请求参数：pageIndex传的是2还是3？
2. 看后端返回：是200空数组，还是404/500？
3. 看SQL：OFFSET值是否已经越过总记录数？

我遇到过一个典型案例：前端把pageIndex从1开始传，后端却按0开始处理，第一页、第二页看似正常（因为前端传1，后端当成第2页，数据范围恰好重叠，部分数据还没暴露出来），翻到第三页就开始错乱。这种隐性错位比一眼就对不上更麻烦，因为它只在特定页码才暴露。

5.2 数据重复与遗漏

翻页数据重复，多数是排序不稳定造成的。列表按created_at排序，如果同一秒内有多条记录，先后顺序不确定，数据库每次查询返回的相邻边界就可能不同，导致第2页的第一条和第1页的最后一条是同一条数据。

解决方案是把排序键写成复合的，比如：

ORDER BY created_at DESC, id DESC

id作为唯一值兜底，顺序就固定住了。千万别用只有日期没有时间戳的字段排序，更别用非唯一字段单独排序。这个坑在日志类数据里尤其常见，因为同一秒的日志量特别大。

5.3 查询性能突然变差

某天接口响应从200ms变成2s，多半是数据量涨了，或者慢查询出现了。先看执行计划，确认ORDER BY和WHERE字段是否命中索引。例如：

EXPLAIN SELECT ... FROM quotation ORDER BY created_at DESC, id DESC LIMIT 20 OFFSET 10000;

如果Extra列出现Using filesort，索引基本没帮上忙。可以补一个(created_at, id)的联合索引试试。深分页场景如果无法避免，至少把pageSize限制小一点，OFFSET带来的扫描行数会少很多。

5.4 页码状态丢失与缓存污染

SPA应用里，用户切到第5页，刷新页面又回到第1页，多数是因为页码只存在组件的局部state里，没有持久化到URL query。我习惯把pageIndex和pageSize同步到路由query参数，比如/quotations?pageIndex=4&pageSize=20，这样刷新、分享、前进后退都保得住状态。另外，如果列表使用了keep-alive缓存，从详情页返回时页码虽然还在，但数据可能已过期，需要在activated钩子里做一次刷新判断。

5.5 总结成速查表

6. 一点自己的体会

分页这个东西，看起来是增删改查里最不起眼的角落，可我这些年调过的分页问题，十个里有八个不是SQL写错，而是约定没定好、边界没处理、排序没兜底。我真正体会到规范性价值，是一次大范围接口联调：所有后端接口的pageIndex从0开始、pageSize有上限、返回结构带totalPages、前端封装统一减一，结果后端兄弟几乎没有因为分页来回扯皮过。

如果你现在正要给项目加一个分页接口，我建议先写一段注释到接口文档里：“pageIndex从0开始，第一页为0；pageSize建议20，最大200。”就这么一句话，至少能省下两轮联调时间。如果项目里已经有分页接口在跑，可以把上面5节当一份排查清单用，先查参数起点，再查排序唯一性，最后查SQL执行计划，多数问题都能对号入座。最后再分享一个小技巧：前端联调时，可以在请求库里临时把pageIndex + 1，看看返回数据和页码对不对得上。如果对不上，八成是后端和前端对这个参数的理解不一样，早发现早改，别等集成测试再炸。