游标分页使用指向最后已见项目的不透明令牌分批返回列表,使分页期间新消息到达也不会移动或重复结果,这一点优于页码。
偏移量分页请求的是“第 201 至 300 项”。它很简单,但列表若在读取过程中发生变化,它就会出错:两次请求之间新建的一条消息会让之后的每一项都后移一位,于是分页边界处要么有一项重复,要么有一项被跳过。偏移量很大时还会很慢,因为数据库必须逐一数过所有被跳过的项。
游标标识的是位置,而不是偏移量。服务器把上一页结束的位置(通常是最后一项的排序键和 ID)编码成一个不透明令牌;客户端把令牌传回以获取下一页,服务器则恰好从那个位置继续。在按最新优先排序的列表中,新项出现在列表开头,不会干扰正在进行的遍历;之后的遍历会把它们取到。响应通常包含各项数据、用于下一页的游标,以及一个表示是否还有更多页的标志。
其中的取舍是有意为之的:不能直接跳到第 40 页,通常没有总数,而且各页只能依次获取,不能并行。
示例
假设一个对账任务按最新优先的顺序读取过去一小时的消息,每次读取一百条,而新流量仍在不断到达。如果使用偏移量,每条新消息都会把它下面的分页往后推,有些消息就会被计算两次。如果使用游标,每个请求都从上次看到的最后一条消息之后继续,每条消息只会被计算一次。
常见错误
- 解析或自行构造游标;游标在设计上就是不透明的,其格式随时可能变化。
- 在遍历中途更改筛选条件,却继续使用旧游标。
- 遇到第一个不满或为空的页面就停止,而不检查标志。
- 通过翻页列表来跟踪本可由 Webhook 推送的状态变化。
在 SMSMeteor:GET /v1/messages 以游标分页方式列出和筛选消息:limit 取值为 1 至 200,默认为 50;cursor 是从上一页的 next_cursor 获得的不透明游标。每个响应都包含 data、next_cursor 和 has_more;只要 has_more 为 true,就继续翻页。消息记录保留 90 天,群发任务摘要则无限期保留。如果只需一次性提取,使用 CSV 或 JSON 格式的报告导出可能更简单;Webhook 则会在 sent、delivered 和 failed 事件发生时即时推送。详情见 API 参考。
