1. 从“翻页”到“翻车”为什么Offset/Limit不再是银弹做后端开发尤其是处理过列表数据接口的同行一定对OFFSET和LIMIT这对“黄金搭档”不陌生。无论是管理后台的用户列表还是电商App的商品瀑布流一句简单的SELECT * FROM table ORDER BY id DESC LIMIT 20 OFFSET 40似乎就能解决所有分页问题。在数据量小、并发低的年代这确实是简单粗暴又有效的方案。但不知道从什么时候开始我发现自己开始频繁地收到告警数据库CPU飙升、接口响应时间从几十毫秒飙升至数秒、甚至直接超时。排查下来罪魁祸首往往就是那些看似无害的深度分页查询。问题的核心在于OFFSET的工作原理。当你执行OFFSET 10000 LIMIT 20时数据库并不是直接跳到第10000条记录开始返回20条。以MySQL的InnoDB引擎为例它需要先完整地扫描并排序前10020条符合条件的数据然后才丢弃前10000条把最后的20条给你。这个过程会产生巨大的O(N)计算和I/O开销。随着OFFSET值的增大性能呈线性甚至更差的速度下降。这就像让你从一本10000页的书中找到第5000页的内容你不是直接翻到那一页而是必须一页一页地数过去效率可想而知。更糟糕的是在动态数据场景下。假设用户正在浏览一个实时更新的帖子列表采用OFFSET/LIMIT分页。当用户翻到第5页时如果第1页有新的帖子插入ORDER BY create_time DESC那么原来第5页的第一条数据就会“漂移”到第6页导致用户看到重复数据反之如果前面的数据被删除则会导致数据被跳过。这种体验非常糟糕。而网络热词中频繁出现的exceeded retry limit、rate limit、too many requests等错误往往就是这种低效查询拖垮数据库后引发的连锁反应——应用层请求超时后不断重试最终触发系统的限流熔断机制。codex exceeded retry limit这类错误提示其根源可能就藏在一个不经意的深度分页API里。因此是时候为我们的分页策略翻开新篇章了。游标分页Cursor-based Pagination正是为了解决上述痛点而生的更优解。它不是简单地用新语法替换旧语法而是一种从设计思想上根本不同的数据获取模式。2. 游标分页的核心思想记住“位置”而非“页码”游标分页有时也叫“键集分页”Keyset Pagination其核心思想非常直观不再使用页码和偏移量而是使用一个指向特定记录的“游标”Cursor来标记我们上次离开的位置然后基于这个游标获取下一页的数据。这个“游标”通常是你排序字段如自增ID、创建时间戳的一个唯一值。举个例子我们有一个用户表按创建时间created_at降序排列。传统的分页请求是GET /users?page5size20。而游标分页的请求则是GET /users?cursoreyJjcmVhdGVkX2F0IjoxNjM4MDQwMDAwLCJpZCI6MTAwfQsize20。这里的cursor是一个编码后的字符串包含了上一页最后一条记录的created_at和id信息。它的工作原理可以用一个简单的SQL对比来理解传统分页第n页:SELECT * FROM posts ORDER BY created_at DESC, id DESC LIMIT 20 OFFSET ((n-1) * 20);性能随n增大而恶化。游标分页基于上一页最后一条记录:SELECT * FROM posts WHERE (created_at ? OR (created_at ? AND id ?)) ORDER BY created_at DESC, id DESC LIMIT 20;这里的?对应上一页最后一条记录的created_at和id。这个查询能高效地利用(created_at, id)上的复合索引直接定位到起始点然后扫描接下来的20条记录。无论你要获取第1页还是第1000页的数据其性能都是稳定且高效的O(1)或O(log N)。为什么游标能解决深度分页和动态数据问题性能恒定它避免了OFFSET带来的大量无效扫描查询时间只与LIMIT的大小有关与数据位置无关。数据稳定性由于查询条件是基于“某个时间点之后/之前的记录”在数据插入或删除时只会影响游标之前或之后的数据不会导致当前浏览窗口内的数据出现重复或丢失假设排序字段是单调递增的。用户就像拿着一枚书签无论书本前面增加了多少页书签之后的内容是稳定的。当然游标分页并非没有代价。它失去了随机跳转到任意页码的能力比如直接跳到第100页但这在无限滚动的Feed流、聊天记录、时间线等场景下恰恰不是需求反而是优点。它让API的使用模式更符合这些场景的自然交互。3. 游标分页的三种实现模式与选型理解了思想我们来看看具体怎么实现。游标分页主要有三种模式适用于不同的排序和数据结构。3.1 基于自增主键或单调递增字段这是最简单、最理想的场景。假设你的表有一个自增的BIGINT类型主键id并且你按id排序。客户端请求首次请求不带游标后续请求携带last_id上一页最后一条记录的ID。服务端SQL-- 第一页 SELECT * FROM items ORDER BY id ASC LIMIT 20; -- 后续页 SELECT * FROM items WHERE id ?last_id ORDER BY id ASC LIMIT 20;优点实现极其简单性能最佳WHERE id ?能完美利用主键索引。缺点排序方式单一通常只能按ID顺序且如果ID不连续有删除操作也不影响功能只是“页”的数据量可能略少于LIMIT。适用场景任何按创建顺序ID通常与创建时间正相关展示的列表如后台操作日志、订单列表按订单号。3.2 基于时间戳及唯一标识符这是更通用的场景也是最常见的游标实现方式。我们通常按created_at创建时间降序排列。但仅用时间戳是不够的因为同一毫秒内可能有多条记录。客户端请求游标需要包含两个值last_created_at和last_id。服务端SQLSELECT * FROM posts WHERE (created_at ?last_created_at) OR (created_at ?last_created_at AND id ?last_id) ORDER BY created_at DESC, id DESC LIMIT 20;关键点复合索引必须在(created_at DESC, id DESC)上建立复合索引这是查询高效的基石。稳定性即使两条记录created_at完全相同通过引入唯一的id作为二级排序条件也能保证排序的绝对确定性和游标的唯一性。方向注意WHERE子句中的比较符号或需要与ORDER BY的顺序DESC或ASC相匹配。上面例子是“获取比某个时间点更早的记录”。适用场景几乎所有的社交动态、新闻资讯、商品列表等按时间倒序排列的场景。3.3 基于其他复杂排序键如分数、热度在一些榜单、热度排序场景下排序依据可能是计算出来的分数score它可能随时间变化。此时游标需要包含分数和唯一ID。客户端请求游标包含last_score和last_id。服务端SQLSELECT * FROM leaderboard WHERE (score ?last_score) OR (score ?last_score AND id ?last_id) ORDER BY score DESC, id DESC LIMIT 20;挑战如果score是实时更新的用户在翻页过程中数据的顺序可能已经改变导致看到重复或跳过的数据。这是业务逻辑决定的游标分页本身无法完全避免但它能保证在查询执行的那一刻数据切片是准确的比OFFSET的“漂移”要可控得多。应对策略对于实时性要求极高的榜单可以考虑使用 Redis Sorted Set 等数据结构或者定期如每分钟生成一次静态快照用于分页查询。选型心得在大部分业务中基于时间戳ID的模式是首选。它平衡了通用性、性能和实现复杂度。自增主键模式虽然简单但业务上按时间排序的需求远多于按ID排序。在决定前一定要和产品经理确认“用户真的需要跳转到任意页码吗” 十有八九答案是否定的。4. 前后端协作API设计、游标编码与状态管理游标分页的实现需要前后端紧密配合。一套清晰的API契约至关重要。4.1 API设计规范一个良好的游标分页API响应格式如下{ data: [...], // 当前页的数据列表 pagination: { next_cursor: eyJjcmVhdGVkX2F0IjoxNjM4MDQwMDAwLCJpZCI6MTAwfQ, has_more: true, prev_cursor: null // 可选如果支持向前翻页 } }next_cursor: 用于获取下一页的游标。它应该基于当前页最后一条记录的排序字段值生成。has_more: 一个布尔值指示是否还有更多数据。这是避免客户端无效请求的关键。判断逻辑是查询时我们请求LIMIT 1条记录例如要20条实际查21条。如果返回了21条则说明还有下一页我们只返回前20条给客户端并将第20条作为生成next_cursor的依据同时设置has_more: true。如果只返回了≤20条则设置has_more: false且next_cursor可以为空。prev_cursor: 如果需要支持“上一页”功能在App中较常见则需要基于当前页第一条记录生成一个指向前一页的游标。实现逻辑与next_cursor对称但WHERE条件的方向相反。4.2 游标的编码与安全游标本身包含的是数据如ID、时间戳直接暴露给客户端可能存在安全或信息泄露风险例如暴露数据量、增长规律。因此务必对游标进行编码。不推荐明文传递?last_id100last_time1638040000。推荐做法Base64编码将包含游标信息的JSON对象序列化后进行Base64编码。这是最常用的方法简单有效。// Node.js 示例 const cursorInfo { created_at: 1638040000, id: 100 }; const nextCursor Buffer.from(JSON.stringify(cursorInfo)).toString(base64); // 返回给前端eyJjcmVhdGVkX2F0IjoxNjM4MDQwMDAwLCJpZCI6MTAwfQ加密对于安全性要求更高的场景可以使用对称加密如AES对游标信息进行加密。客户端无需解密原样传回即可。数据库ID另一种取巧的方式是游标直接使用数据库中的某个唯一、连续且与排序相关的字段如一个专门用于分页的自增序列服务端根据这个ID反查出对应的created_at等值再构造查询。这增加了服务端复杂度但对外完全隐藏了业务字段。重要提示无论采用哪种编码都要确保游标是不透明opaque的。即客户端不应尝试解析或修改它只应将其视为一个用于获取下一页的令牌。这为后端未来改变游标实现方式提供了灵活性。4.3 客户端的处理逻辑前端或移动端在处理游标分页时逻辑也需要调整首次加载不传递cursor参数。加载更多将上一次响应中的pagination.next_cursor作为参数发起下一次请求。判断终止当has_more为false时停止加载更多。列表合并将新获取的data追加到现有列表末尾。下拉刷新这是一个独立的操作通常会清空当前列表和游标重新从第一页开始加载。注意不要和“加载更多”的游标混淆。5. 实战踩坑游标分页的边界条件与复杂场景游标分页虽好但在实际落地时会遇到一些比OFFSET更“微妙”的问题。下面是我在多个项目中总结的实战经验和坑点。5.1 过滤条件WHERE与游标的兼容性这是最容易出错的地方。当列表有过滤条件时比如“只查看某个作者的文章”游标必须在这个过滤后的子集内保持唯一性和顺序性。错误示范-- 假设游标基于 (created_at, id) SELECT * FROM posts WHERE author_id 123 AND (created_at ?last_created_at OR (created_at ?last_created_at AND id ?last_id)) ORDER BY created_at DESC, id DESC LIMIT 20;这个查询在大多数情况下是没问题的。但想象一个极端情况游标指向的记录(created_atT1, id100)它本身author_id不等于123。那么WHERE条件author_id123可能会把这条记录过滤掉导致我们实际上是从一个“错误”的起点开始查询可能丢失数据。正确做法确保用于生成游标的记录本身也满足所有稳定的过滤条件。如果过滤条件可能把游标记录本身排除那么游标就失效了。对于动态过滤如搜索关键词游标分页可能不是最佳选择或者需要更复杂的方案如搜索引擎提供的search_after参数。5.2 排序字段的选取与索引设计游标分页的性能完全依赖于索引。必须建立复合索引对于ORDER BY created_at DESC, id DESC最理想的索引是(created_at DESC, id DESC)。如果数据库不支持索引中指定排序方向如MySQL的InnoDB索引列默认升序创建(created_at, id)也可以但查询计划器在反向扫描时效率可能略低。排序字段必须唯一如果created_at可能重复必须加上第二个字段如id来保证游标的唯一性。否则当游标落在重复的时间戳上时翻页会出现数据重复或丢失。避免使用可变的排序字段例如使用一个经常被更新的update_time作为游标字段是非常危险的因为记录的位置可能在两次查询间发生变化。5.3 “上一页”功能的实现实现“下一页”是顺向的实现“上一页”则需要逆向思维。你需要一个基于当前页第一条记录的prev_cursor。服务端逻辑查询时你需要知道当前页的第一条记录。然后构造一个反向查询-- 假设当前页第一条记录是 (first_created_at, first_id) SELECT * FROM posts WHERE (created_at ?first_created_at) OR (created_at ?first_created_at AND id ?first_id) ORDER BY created_at ASC, id ASC -- 注意排序方向相反 LIMIT 20;查询出来后为了保持和“下一页”一致的顺序通常是倒序你还需要在内存中将这20条记录反转一下顺序。同样需要查询LIMIT1条来判断是否有“上一页”。客户端存储客户端需要同时维护next_cursor和prev_cursor或者在跳转时能够传递当前页的边界游标。5.4 与搜索引擎Elasticsearch的集成对于使用Elasticsearch进行全文搜索和复杂查询的场景游标分页有官方的完美支持search_after参数。原理与数据库游标类似search_after接受一个由排序字段值组成的数组指示从哪个点之后开始搜索。示例// 第一页 { query: { match_all: {} }, sort: [{created_at: desc}, {_id: desc}], size: 20 } // 第二页使用第一页最后一条的排序值 { query: { match_all: {} }, sort: [{created_at: desc}, {_id: desc}], size: 20, search_after: [1638040000, 100] }优势完美解决深度分页性能问题对比fromsize并且能很好地与复杂的查询DSL结合。注意和数据库一样需要保证排序字段组合的唯一性通常用_id作为最后一道排序保障。6. 性能对比实测与迁移策略理论说再多不如实际跑个分。我在一个约1000万条记录的测试表上进行了对比实验该表在created_at和id上有复合索引。测试查询获取按created_at倒序排列的数据。分页方式查询语句示例获取第1页耗时获取第1000页约第20000条耗时获取第5000页约第100000条耗时Offset/LimitLIMIT 20 OFFSET 0~2 ms~450 ms~2200 msOffset/LimitLIMIT 20 OFFSET 20000~450 ms~450 ms~2200 msOffset/LimitLIMIT 20 OFFSET 100000~2200 ms~450 ms~2200 ms游标分页WHERE created_at ? ...~2 ms~2 ms~2 ms结果一目了然。OFFSET的性能随着深度急剧下降而游标分页的性能几乎是一条水平线。当你的应用用户开始频繁浏览深度页面时这种差异会直接转化为数据库的负载和用户的等待时间。那么如何从旧的OFFSET/LIMITAPI 迁移到游标分页这是一个需要谨慎处理的破坏性变更。粗暴地切换会导致所有客户端Web、iOS、Android无法正确翻页。API版本化推荐为游标分页设计一个新的API端点例如/v2/users旧的/v1/users?pagesize保持不变。让客户端逐步迁移到新版本。参数兼容与适配如果无法做版本化可以尝试在同一个端点支持两种模式。例如优先检查cursor参数如果存在则用游标逻辑如果不存在但存在page参数则使用旧的OFFSET逻辑并在响应中同时返回游标信息引导客户端下次使用游标。同时在文档和日志中标记旧参数为“已废弃”。客户端渐进升级推动客户端发版使用新的游标逻辑。在过渡期服务端可以同时支持两种方式但需要监控旧接口的调用量待其降至极低水平后再考虑下线。迁移的核心是保证兼容性平滑过渡。不要小看客户端的升级成本尤其是移动端App。7. 不是万能药游标分页的局限性与替代方案游标分页虽好但并非所有场景都适用。认清它的边界才能做出正确的技术选型。局限1无法随机跳页。这是游标分页最大的特点也是最大的限制。对于后台管理系统、报表导出等需要指定页码或随机访问的场景游标分页不适用。局限2对排序字段要求严格。必须有一个稳定、唯一或能组合成唯一的排序字段。对于无法建立这种稳定排序的查询例如按“相似度”排序的模糊搜索结果实现起来很困难。局限3实现复杂度更高。前后端都需要额外的逻辑来处理游标的编码、解码和状态管理。当游标分页不适用时可以考虑以下替代或混合方案“seek method” / “keyset pagination” 的变种本质还是游标思想但可以应对更复杂的排序。例如按“点赞数”和“时间”综合排序的热门列表可以使用(score, id)作为游标。流式分页 / 时间范围分页对于日志、时间线数据有时可以完全放弃“页”的概念改为基于时间范围的查询。例如客户端记录当前已看到的最旧时间戳下次请求时直接请求这个时间戳之前的数据。这更接近“无限流”的本质。保留Offset/Limit用于特定场景在需要随机访问的管理后台可以继续使用OFFSET/LIMIT但必须严格限制分页深度例如通过业务逻辑或中间件禁止OFFSET超过一个阈值如1000并结合高效的WHERE条件来缩小扫描范围。最终的选择取决于你的具体业务需求、数据规模和用户体验要求。没有一种分页方案是完美的但了解每种方案的优劣能帮助我们在架构设计时做出更明智的决策。从OFFSET到游标不仅仅是换一个查询条件更是从“面向页码”到“面向数据流”思维模式的转变。 从Offset到游标分页：高性能分页查询的工程实践
1. 从“翻页”到“翻车”为什么Offset/Limit不再是银弹做后端开发尤其是处理过列表数据接口的同行一定对OFFSET和LIMIT这对“黄金搭档”不陌生。无论是管理后台的用户列表还是电商App的商品瀑布流一句简单的SELECT * FROM table ORDER BY id DESC LIMIT 20 OFFSET 40似乎就能解决所有分页问题。在数据量小、并发低的年代这确实是简单粗暴又有效的方案。但不知道从什么时候开始我发现自己开始频繁地收到告警数据库CPU飙升、接口响应时间从几十毫秒飙升至数秒、甚至直接超时。排查下来罪魁祸首往往就是那些看似无害的深度分页查询。问题的核心在于OFFSET的工作原理。当你执行OFFSET 10000 LIMIT 20时数据库并不是直接跳到第10000条记录开始返回20条。以MySQL的InnoDB引擎为例它需要先完整地扫描并排序前10020条符合条件的数据然后才丢弃前10000条把最后的20条给你。这个过程会产生巨大的O(N)计算和I/O开销。随着OFFSET值的增大性能呈线性甚至更差的速度下降。这就像让你从一本10000页的书中找到第5000页的内容你不是直接翻到那一页而是必须一页一页地数过去效率可想而知。更糟糕的是在动态数据场景下。假设用户正在浏览一个实时更新的帖子列表采用OFFSET/LIMIT分页。当用户翻到第5页时如果第1页有新的帖子插入ORDER BY create_time DESC那么原来第5页的第一条数据就会“漂移”到第6页导致用户看到重复数据反之如果前面的数据被删除则会导致数据被跳过。这种体验非常糟糕。而网络热词中频繁出现的exceeded retry limit、rate limit、too many requests等错误往往就是这种低效查询拖垮数据库后引发的连锁反应——应用层请求超时后不断重试最终触发系统的限流熔断机制。codex exceeded retry limit这类错误提示其根源可能就藏在一个不经意的深度分页API里。因此是时候为我们的分页策略翻开新篇章了。游标分页Cursor-based Pagination正是为了解决上述痛点而生的更优解。它不是简单地用新语法替换旧语法而是一种从设计思想上根本不同的数据获取模式。2. 游标分页的核心思想记住“位置”而非“页码”游标分页有时也叫“键集分页”Keyset Pagination其核心思想非常直观不再使用页码和偏移量而是使用一个指向特定记录的“游标”Cursor来标记我们上次离开的位置然后基于这个游标获取下一页的数据。这个“游标”通常是你排序字段如自增ID、创建时间戳的一个唯一值。举个例子我们有一个用户表按创建时间created_at降序排列。传统的分页请求是GET /users?page5size20。而游标分页的请求则是GET /users?cursoreyJjcmVhdGVkX2F0IjoxNjM4MDQwMDAwLCJpZCI6MTAwfQsize20。这里的cursor是一个编码后的字符串包含了上一页最后一条记录的created_at和id信息。它的工作原理可以用一个简单的SQL对比来理解传统分页第n页:SELECT * FROM posts ORDER BY created_at DESC, id DESC LIMIT 20 OFFSET ((n-1) * 20);性能随n增大而恶化。游标分页基于上一页最后一条记录:SELECT * FROM posts WHERE (created_at ? OR (created_at ? AND id ?)) ORDER BY created_at DESC, id DESC LIMIT 20;这里的?对应上一页最后一条记录的created_at和id。这个查询能高效地利用(created_at, id)上的复合索引直接定位到起始点然后扫描接下来的20条记录。无论你要获取第1页还是第1000页的数据其性能都是稳定且高效的O(1)或O(log N)。为什么游标能解决深度分页和动态数据问题性能恒定它避免了OFFSET带来的大量无效扫描查询时间只与LIMIT的大小有关与数据位置无关。数据稳定性由于查询条件是基于“某个时间点之后/之前的记录”在数据插入或删除时只会影响游标之前或之后的数据不会导致当前浏览窗口内的数据出现重复或丢失假设排序字段是单调递增的。用户就像拿着一枚书签无论书本前面增加了多少页书签之后的内容是稳定的。当然游标分页并非没有代价。它失去了随机跳转到任意页码的能力比如直接跳到第100页但这在无限滚动的Feed流、聊天记录、时间线等场景下恰恰不是需求反而是优点。它让API的使用模式更符合这些场景的自然交互。3. 游标分页的三种实现模式与选型理解了思想我们来看看具体怎么实现。游标分页主要有三种模式适用于不同的排序和数据结构。3.1 基于自增主键或单调递增字段这是最简单、最理想的场景。假设你的表有一个自增的BIGINT类型主键id并且你按id排序。客户端请求首次请求不带游标后续请求携带last_id上一页最后一条记录的ID。服务端SQL-- 第一页 SELECT * FROM items ORDER BY id ASC LIMIT 20; -- 后续页 SELECT * FROM items WHERE id ?last_id ORDER BY id ASC LIMIT 20;优点实现极其简单性能最佳WHERE id ?能完美利用主键索引。缺点排序方式单一通常只能按ID顺序且如果ID不连续有删除操作也不影响功能只是“页”的数据量可能略少于LIMIT。适用场景任何按创建顺序ID通常与创建时间正相关展示的列表如后台操作日志、订单列表按订单号。3.2 基于时间戳及唯一标识符这是更通用的场景也是最常见的游标实现方式。我们通常按created_at创建时间降序排列。但仅用时间戳是不够的因为同一毫秒内可能有多条记录。客户端请求游标需要包含两个值last_created_at和last_id。服务端SQLSELECT * FROM posts WHERE (created_at ?last_created_at) OR (created_at ?last_created_at AND id ?last_id) ORDER BY created_at DESC, id DESC LIMIT 20;关键点复合索引必须在(created_at DESC, id DESC)上建立复合索引这是查询高效的基石。稳定性即使两条记录created_at完全相同通过引入唯一的id作为二级排序条件也能保证排序的绝对确定性和游标的唯一性。方向注意WHERE子句中的比较符号或需要与ORDER BY的顺序DESC或ASC相匹配。上面例子是“获取比某个时间点更早的记录”。适用场景几乎所有的社交动态、新闻资讯、商品列表等按时间倒序排列的场景。3.3 基于其他复杂排序键如分数、热度在一些榜单、热度排序场景下排序依据可能是计算出来的分数score它可能随时间变化。此时游标需要包含分数和唯一ID。客户端请求游标包含last_score和last_id。服务端SQLSELECT * FROM leaderboard WHERE (score ?last_score) OR (score ?last_score AND id ?last_id) ORDER BY score DESC, id DESC LIMIT 20;挑战如果score是实时更新的用户在翻页过程中数据的顺序可能已经改变导致看到重复或跳过的数据。这是业务逻辑决定的游标分页本身无法完全避免但它能保证在查询执行的那一刻数据切片是准确的比OFFSET的“漂移”要可控得多。应对策略对于实时性要求极高的榜单可以考虑使用 Redis Sorted Set 等数据结构或者定期如每分钟生成一次静态快照用于分页查询。选型心得在大部分业务中基于时间戳ID的模式是首选。它平衡了通用性、性能和实现复杂度。自增主键模式虽然简单但业务上按时间排序的需求远多于按ID排序。在决定前一定要和产品经理确认“用户真的需要跳转到任意页码吗” 十有八九答案是否定的。4. 前后端协作API设计、游标编码与状态管理游标分页的实现需要前后端紧密配合。一套清晰的API契约至关重要。4.1 API设计规范一个良好的游标分页API响应格式如下{ data: [...], // 当前页的数据列表 pagination: { next_cursor: eyJjcmVhdGVkX2F0IjoxNjM4MDQwMDAwLCJpZCI6MTAwfQ, has_more: true, prev_cursor: null // 可选如果支持向前翻页 } }next_cursor: 用于获取下一页的游标。它应该基于当前页最后一条记录的排序字段值生成。has_more: 一个布尔值指示是否还有更多数据。这是避免客户端无效请求的关键。判断逻辑是查询时我们请求LIMIT 1条记录例如要20条实际查21条。如果返回了21条则说明还有下一页我们只返回前20条给客户端并将第20条作为生成next_cursor的依据同时设置has_more: true。如果只返回了≤20条则设置has_more: false且next_cursor可以为空。prev_cursor: 如果需要支持“上一页”功能在App中较常见则需要基于当前页第一条记录生成一个指向前一页的游标。实现逻辑与next_cursor对称但WHERE条件的方向相反。4.2 游标的编码与安全游标本身包含的是数据如ID、时间戳直接暴露给客户端可能存在安全或信息泄露风险例如暴露数据量、增长规律。因此务必对游标进行编码。不推荐明文传递?last_id100last_time1638040000。推荐做法Base64编码将包含游标信息的JSON对象序列化后进行Base64编码。这是最常用的方法简单有效。// Node.js 示例 const cursorInfo { created_at: 1638040000, id: 100 }; const nextCursor Buffer.from(JSON.stringify(cursorInfo)).toString(base64); // 返回给前端eyJjcmVhdGVkX2F0IjoxNjM4MDQwMDAwLCJpZCI6MTAwfQ加密对于安全性要求更高的场景可以使用对称加密如AES对游标信息进行加密。客户端无需解密原样传回即可。数据库ID另一种取巧的方式是游标直接使用数据库中的某个唯一、连续且与排序相关的字段如一个专门用于分页的自增序列服务端根据这个ID反查出对应的created_at等值再构造查询。这增加了服务端复杂度但对外完全隐藏了业务字段。重要提示无论采用哪种编码都要确保游标是不透明opaque的。即客户端不应尝试解析或修改它只应将其视为一个用于获取下一页的令牌。这为后端未来改变游标实现方式提供了灵活性。4.3 客户端的处理逻辑前端或移动端在处理游标分页时逻辑也需要调整首次加载不传递cursor参数。加载更多将上一次响应中的pagination.next_cursor作为参数发起下一次请求。判断终止当has_more为false时停止加载更多。列表合并将新获取的data追加到现有列表末尾。下拉刷新这是一个独立的操作通常会清空当前列表和游标重新从第一页开始加载。注意不要和“加载更多”的游标混淆。5. 实战踩坑游标分页的边界条件与复杂场景游标分页虽好但在实际落地时会遇到一些比OFFSET更“微妙”的问题。下面是我在多个项目中总结的实战经验和坑点。5.1 过滤条件WHERE与游标的兼容性这是最容易出错的地方。当列表有过滤条件时比如“只查看某个作者的文章”游标必须在这个过滤后的子集内保持唯一性和顺序性。错误示范-- 假设游标基于 (created_at, id) SELECT * FROM posts WHERE author_id 123 AND (created_at ?last_created_at OR (created_at ?last_created_at AND id ?last_id)) ORDER BY created_at DESC, id DESC LIMIT 20;这个查询在大多数情况下是没问题的。但想象一个极端情况游标指向的记录(created_atT1, id100)它本身author_id不等于123。那么WHERE条件author_id123可能会把这条记录过滤掉导致我们实际上是从一个“错误”的起点开始查询可能丢失数据。正确做法确保用于生成游标的记录本身也满足所有稳定的过滤条件。如果过滤条件可能把游标记录本身排除那么游标就失效了。对于动态过滤如搜索关键词游标分页可能不是最佳选择或者需要更复杂的方案如搜索引擎提供的search_after参数。5.2 排序字段的选取与索引设计游标分页的性能完全依赖于索引。必须建立复合索引对于ORDER BY created_at DESC, id DESC最理想的索引是(created_at DESC, id DESC)。如果数据库不支持索引中指定排序方向如MySQL的InnoDB索引列默认升序创建(created_at, id)也可以但查询计划器在反向扫描时效率可能略低。排序字段必须唯一如果created_at可能重复必须加上第二个字段如id来保证游标的唯一性。否则当游标落在重复的时间戳上时翻页会出现数据重复或丢失。避免使用可变的排序字段例如使用一个经常被更新的update_time作为游标字段是非常危险的因为记录的位置可能在两次查询间发生变化。5.3 “上一页”功能的实现实现“下一页”是顺向的实现“上一页”则需要逆向思维。你需要一个基于当前页第一条记录的prev_cursor。服务端逻辑查询时你需要知道当前页的第一条记录。然后构造一个反向查询-- 假设当前页第一条记录是 (first_created_at, first_id) SELECT * FROM posts WHERE (created_at ?first_created_at) OR (created_at ?first_created_at AND id ?first_id) ORDER BY created_at ASC, id ASC -- 注意排序方向相反 LIMIT 20;查询出来后为了保持和“下一页”一致的顺序通常是倒序你还需要在内存中将这20条记录反转一下顺序。同样需要查询LIMIT1条来判断是否有“上一页”。客户端存储客户端需要同时维护next_cursor和prev_cursor或者在跳转时能够传递当前页的边界游标。5.4 与搜索引擎Elasticsearch的集成对于使用Elasticsearch进行全文搜索和复杂查询的场景游标分页有官方的完美支持search_after参数。原理与数据库游标类似search_after接受一个由排序字段值组成的数组指示从哪个点之后开始搜索。示例// 第一页 { query: { match_all: {} }, sort: [{created_at: desc}, {_id: desc}], size: 20 } // 第二页使用第一页最后一条的排序值 { query: { match_all: {} }, sort: [{created_at: desc}, {_id: desc}], size: 20, search_after: [1638040000, 100] }优势完美解决深度分页性能问题对比fromsize并且能很好地与复杂的查询DSL结合。注意和数据库一样需要保证排序字段组合的唯一性通常用_id作为最后一道排序保障。6. 性能对比实测与迁移策略理论说再多不如实际跑个分。我在一个约1000万条记录的测试表上进行了对比实验该表在created_at和id上有复合索引。测试查询获取按created_at倒序排列的数据。分页方式查询语句示例获取第1页耗时获取第1000页约第20000条耗时获取第5000页约第100000条耗时Offset/LimitLIMIT 20 OFFSET 0~2 ms~450 ms~2200 msOffset/LimitLIMIT 20 OFFSET 20000~450 ms~450 ms~2200 msOffset/LimitLIMIT 20 OFFSET 100000~2200 ms~450 ms~2200 ms游标分页WHERE created_at ? ...~2 ms~2 ms~2 ms结果一目了然。OFFSET的性能随着深度急剧下降而游标分页的性能几乎是一条水平线。当你的应用用户开始频繁浏览深度页面时这种差异会直接转化为数据库的负载和用户的等待时间。那么如何从旧的OFFSET/LIMITAPI 迁移到游标分页这是一个需要谨慎处理的破坏性变更。粗暴地切换会导致所有客户端Web、iOS、Android无法正确翻页。API版本化推荐为游标分页设计一个新的API端点例如/v2/users旧的/v1/users?pagesize保持不变。让客户端逐步迁移到新版本。参数兼容与适配如果无法做版本化可以尝试在同一个端点支持两种模式。例如优先检查cursor参数如果存在则用游标逻辑如果不存在但存在page参数则使用旧的OFFSET逻辑并在响应中同时返回游标信息引导客户端下次使用游标。同时在文档和日志中标记旧参数为“已废弃”。客户端渐进升级推动客户端发版使用新的游标逻辑。在过渡期服务端可以同时支持两种方式但需要监控旧接口的调用量待其降至极低水平后再考虑下线。迁移的核心是保证兼容性平滑过渡。不要小看客户端的升级成本尤其是移动端App。7. 不是万能药游标分页的局限性与替代方案游标分页虽好但并非所有场景都适用。认清它的边界才能做出正确的技术选型。局限1无法随机跳页。这是游标分页最大的特点也是最大的限制。对于后台管理系统、报表导出等需要指定页码或随机访问的场景游标分页不适用。局限2对排序字段要求严格。必须有一个稳定、唯一或能组合成唯一的排序字段。对于无法建立这种稳定排序的查询例如按“相似度”排序的模糊搜索结果实现起来很困难。局限3实现复杂度更高。前后端都需要额外的逻辑来处理游标的编码、解码和状态管理。当游标分页不适用时可以考虑以下替代或混合方案“seek method” / “keyset pagination” 的变种本质还是游标思想但可以应对更复杂的排序。例如按“点赞数”和“时间”综合排序的热门列表可以使用(score, id)作为游标。流式分页 / 时间范围分页对于日志、时间线数据有时可以完全放弃“页”的概念改为基于时间范围的查询。例如客户端记录当前已看到的最旧时间戳下次请求时直接请求这个时间戳之前的数据。这更接近“无限流”的本质。保留Offset/Limit用于特定场景在需要随机访问的管理后台可以继续使用OFFSET/LIMIT但必须严格限制分页深度例如通过业务逻辑或中间件禁止OFFSET超过一个阈值如1000并结合高效的WHERE条件来缩小扫描范围。最终的选择取决于你的具体业务需求、数据规模和用户体验要求。没有一种分页方案是完美的但了解每种方案的优劣能帮助我们在架构设计时做出更明智的决策。从OFFSET到游标不仅仅是换一个查询条件更是从“面向页码”到“面向数据流”思维模式的转变。