什么是分页？页面、偏移量、游标与滚动

Scrapeless Agent Browser 自动化页面导航和浏览器交互，用于从分页的公共界面收集数据。

分页将集合划分为可检索的部分

分页是将一个集合拆分为更小部分的过程，客户端分别检索或显示这些部分。搜索界面可以显示编号结果页，信息流可以在滚动时添加更多条目，API 可以返回一个延续令牌。每种设计都限制一次处理的信息量，同时为使用方提供获取更多内容的方式。

分页的原因超出了视觉页面设计的范畴。大型集合在查询、序列化、传输、解析和渲染方面都可能耗费大量时间。返回一个有界部分有助于管理这些成本。它还创建了一个客户端必须理解的约定：集合包含哪些项目，它们如何排序，下一部分如何请求，以及什么表示遍历已经结束。

分页并不意味着每一页长度相同、总数可用，或集合在遍历期间保持不变。这些属性取决于服务本身。在收集记录之前，应阅读端点或界面的行为并定义数据集边界。否则，程序即使导航正确，也可能对完整性或历史一致性做出不受支持的声明。

编号页面和偏移量体现位置式导航

页码分页根据特定的页面大小约定请求一个具名页面。偏移量分页要求服务器在返回一个有界部分之前跳过一定数量的项目。当已知它们的索引和页面大小规则时，两者可以进行算术换算，但客户端不应推断这些规则。有些接口的页码从 0 开始，有些则从 1 开始。

当人们希望在一个稳定的集合中找到熟悉的位置或直接跳转页面时，位置式接口很有用。当在请求之间添加或删除项目时，它就更难解释了。在开头附近新增一条记录会移动后续偏移量，因此消费者即使按顺序正确请求位置，也可能两次遇到同一项目或错过某个项目。

“ PostgreSQL LIMIT and OFFSET behavior ”解释了为什么需要可预测的排序，以及为什么一个很大的偏移量仍可能要求服务器计算被跳过的行。这是数据库特定的实现事实，而不是证明每个基于偏移量的 API 都很慢。应评估实际的后端和工作负载，而不是仅凭名称对接口风格进行排序。

游标体现延续边界

游标分页返回一个值，用于标识客户端在有序查询中应从哪里继续。消费者通常会原样发送该值而不去解释它。不透明游标使 API 约定独立于存储细节，而 next 链接还可以保留正确的端点和查询参数。应使用服务明确提供的任一延续机制。

游标通常适用于顺序信息流和大规模有序遍历，但它们本身并不会创建固定快照。令牌可能过期，权限可能变化，可变的排序字段可能移动记录。历史导出需要来源约定在一致性和保留方面满足要求，而不仅仅是某个端点暴露了名为 cursor 的字段。

浏览器分页是一个用户界面约定

浏览器分页描述了人或自动化如何获取另一组可见记录。下一页按钮可以导航到新文档、替换当前列表，或追加更多条目。加载更多控件可以在末尾消失，也可以保持禁用状态。无限滚动可能只在视口达到某个阈值后才触发请求。在选择自动化操作之前，应先观察这些状态。

界面无法可靠透露底层存储方式。编号页面可能调用一个 API，而无限列表可能使用偏移量而不是游标。应将可见操作和网络层的延续视为独立观察。未文档化的内部请求，并不会因为开发者工具能显示它就自动成为稳定的公共 API。

统计记录标识，而不是只依赖 DOM 元素数量。虚拟化界面可以重复利用少量元素来展示更大的集合。追加的重复项可以在不增加新记录的情况下增加元素数量。集合逻辑应识别任务所需的标识字段，并保留已观察到的卡片与新接受记录之间的区别。

排序、过滤和快照边界定义覆盖范围

只有在查询保持可识别时，分页遍历才有清晰含义。将集合名称、过滤条件、排序顺序以及任何受支持的时间边界与结果一起存储。如果用户在任务中途从一个类别切换到另一个，已保存的页面位置就不再描述同一个集合。应开始一次独立的遍历，或遵循服务对该变更的文档化行为。

这份 OpenStack 分页和排序指南 将过滤和排序视为集合接口的一部分。使用方应保留这些规则，而不是将分页视为一个孤立的循环。为了稳定遍历，当多个记录具有相同的可见排序值时，有序键需要一个确定性的决策规则。

对一个在线接口进行完整遍历时，仍然可能跨越不同的源状态。新记录会在采集期间出现，被删除的记录会消失。需要定义报告是描述固定导出中的全部记录，还是描述采集窗口期间观察到的记录。当源不提供快照保证时，应在报告中保留这一限制，而不是把成功的导航转化为更强的完整性声明。

从文档化信号中识别结束位置

结束条件告诉采集器何时不再有属于此次遍历的内容。API 可以省略下一页 token，返回一个为假的继续标志，或不提供下一页链接。浏览器可以禁用其导航控件或显示终止消息。正确的信号取决于接口，而使用方应记录它所采用的是哪一种。

时间限制、页数上限或屏幕内容不变，并不自动等同于来源的结束条件。它们可以是合理的任务边界，但当源中可能还有更多记录时，这些只会产生有界的部分采集。要明确标注这种差异。一个有用的结果应说明是来源结束了、预算用完了、观察窗口结束了，还是接口没有提供足够的证据以继续。

在推进检查点之前存储记录

检查点应代表已经写入持久存储的页面内容。应将查询定义与续传状态一并捕获，提交已接受记录，然后再推进已存储的位置。若反过来操作，若程序在位置更新与记录写入之间停止，就可能跳过数据。应将存储边界视为遍历设计的一部分，而不是事后补充。

在源提供稳定记录标识的情况下，使用这些标识去重。根据任务不同，URL、产品 ID 或其他有文档说明的键都可能适用。仅依赖可见标题文本通常是较弱的标识，因为标题可能重复或改变。保留源标识和观察时间，以便后续处理可以区分重复观察与外观相似但实际上不同的记录。

不要通过猜测未来的 token 来并行化单一的、相互依赖的游标链。下一个位置可能依赖于前一个响应。当源支持独立分区且合并后的范围仍然界定清晰时，可以分别处理这些分区。要考虑这些分区之间共享的请求预算，并记录足够的分区元数据，以便说明它们的结果是如何组合的。

将分页概念应用到托管浏览器

其中的 浏览器分页模式 区分了“下一页”控件、页码、加载更多按钮以及无限滚动。在实现具体行为之前，先使用这些模式识别接口类型。每次跳转后都要保留记录校验，以免访问提示或空的应用外壳在无声无息中变成表面上看似有效的终页。

在评估采集所需资源成本时，请查看 Scrapeless 定价 。一个假设性的类别审计可以从一组有界的、被允许访问的页面开始，记录每个被接受的产品标识，并在接口的明确终止状态处停止。生成的报告应说明观察到的类别、排序顺序、采集窗口和结束证据，以便他人评估其覆盖范围。

根据用户与数据需求选择导航方式

根据任务在导航、一致性和成本方面的需求选择分页设计。人类用户可能需要直接跳页，而自动导出则可能需要稳定的顺序遍历和可靠的续传能力。移动界面可能偏好“加载更多”，但这种便利性并不构成后端一致性保证。将展示方式与记录契约区分开来。

在扩展采集器之前，先使用一个具有代表性的授权集合验证第一次跳转、中间的一次跳转以及最终状态。检查筛选器是否保持激活，记录标识是否保持稳定。有少量但证据清晰的遍历，比一个结尾无法解释的大文件更有用。验收标准应让这些证据对数据集的使用者清晰可见。

结论

分页将导航机制与有序集合契约结合在一起。识别下一步操作，保留查询状态，在每次跳转后验证记录，并记录真实的结束位置。无论来源使用页码、不透明令牌还是动态浏览器界面，这种方法都能生成覆盖范围可评估的数据集。