百万条记录、一万次请求,一行都不能丢
offset 分页翻到末页几乎要扫全表,游标、键集和检查点让大批量拉取又快又不会悄悄重复。
要点速览
- offset 写起来简单,但 offset 越大越慢;拉取过程中数据一变,还可能重复或跳过若干行。数据量大时优先用游标。
- 始终显式设置 limit,排序时加上 id 这类决胜字段,等服务器发出结束信号再停,绝不自己数页数。
- 批次落盘之后再保存游标,并处理 HTTP 429。这样大批量拉取中断后才能续跑,一行不丢。
一个系统有 1,000,000 条记录,每页取 100 行,需要 10,000 次请求。如果 API 像 Stripe 那样默认每页只返回 10 行,而你忘了设置 limit,请求数就变成 100,000。
如果 API 按 offset 分页,最后几页的情况更糟:为了返回你要的 100 行,服务器要扫过将近一百万行,再全部丢掉。
前线部署工程师(FDE)到客户现场接手的第一项任务,往往是从客户系统里拉出工单、交易或消息,用来搭数据管道或喂给 Agent。下游的一切都建立在这一个读取 API 的循环上。
它要是悄悄多拉了五行,或者漏了五行,演示里的每个数字都是错的。
本指南用 Python 写一个数据拉取程序,覆盖三种常见的分页方式,包括过滤、分批、限流处理和检查点。你需要 Python 3、requests 库和一个测试用的 API key。代码针对一个假想的 API,字段名做了简化;实际项目中,请换成客户文档里的字段名。
第 1 步:读文档,弄清 API 属于哪一类
写循环之前,先回答两个问题:API 怎么翻到下一页?怎么知道数据已经取完?下面三个公开 API 代表了最常遇到的几种做法。
| API | 如何继续 | 每页大小 | 停止信号 |
|---|---|---|---|
| Confluence(Atlassian) | 用 start 和 limit 做 offset 分页 |
Atlassian 建议始终显式设置 limit |
响应里不再有 next 链接 |
| Stripe | 按对象 ID 的游标,starting_after / ending_before |
limit 取 1 到 100,默认 10 |
has_more 为 false |
| Slack | 服务器下发的游标 | Slack 建议每次调用 100 到 200 | next_cursor 为空、为 null 或不存在 |
三者的共同点是:何时停止由服务器决定,而不是客户端。这是第一条规则:绝不要事先算出“一共 50 页”,然后循环 50 次。
完成这一步后,你应该能说清客户 API 的三件事:翻页参数叫什么,limit 最大是多少,哪个字段表示数据已取完。
第 2 步:显式设置 limit 的 offset 循环
对于 Confluence 风格的 API,循环跟随 next 链接,而不是自己递增 start。这段代码做了简化:links.next 是占位字段名,请对照真实响应核实。
import requests
def iter_offset(session, url, limit=100):
params = {"start": 0, "limit": limit} # 始终显式设置 limit
while url:
resp = session.get(url, params=params)
resp.raise_for_status()
page = resp.json()
yield from page["results"]
url = page.get("links", {}).get("next") # 没有 next 链接,说明数据已取完
params = None # next 链接里通常已经带了 start/limit
检查:打印每一页的行数。如果你要了 100 行,每页却都正好是 25 行,说明服务器在套用自己的上限。这正是 Atlassian 建议设置 limit 的原因:这样你才能确切知道每页有多少条结果。
为什么 offset 遇到实时数据会出错?
offset 有两个弱点。明显的一个是速度:offset 越大,数据库要扫描并丢弃的行就越多。更危险的一个叫页面漂移(page drift):你翻页的同时,新记录不断写入表中。
以一个按最新优先读取的工单流为例。第 1 页返回第 1 到 100 行。与此同时新建了五张工单,它们最新,于是跳到列表顶端,把所有旧行往下挤了五位。
你用 offset 100 请求第 2 页时,服务器返回的是原来的第 96 到 195 行,于是有五行返回了两次。如果是记录被删除而不是新增,情况正好相反,会跳过五行。
第 3 步:等服务器说停才停的游标循环
游标能避免页面漂移,因为它标记的是“在这条记录之后”,而不是“在第 N 个位置之后”。Stripe 用本页最后一个对象的 ID 作为 starting_after。下面的代码沿用 Stripe 的模式,items 是占位字段名。
def iter_cursor(session, url, limit=100):
params = {"limit": limit} # Stripe 允许 1-100
while True:
resp = session.get(url, params=params)
resp.raise_for_status()
page = resp.json()
items = page["items"]
yield from items
if not page["has_more"] or not items:
break
params["starting_after"] = items[-1]["id"]
对于 Slack 风格的 API,要改停止条件:检查 next_cursor 是否为空、为 null 或不存在,三种情况都要处理。Stripe 的客户端库也支持自动分页。客户允许的话可以直接用,但仍要弄懂底层的循环,出问题时才能调试。
游标也有自己的风险。在 seek/键集风格的分页中,如果用作锚点的记录被删除,它的 ID 可能不再有效,下一次请求就会失败。所以出错时要把最后一个游标记进日志,不要只记 HTTP 状态码。
第 4 步:用过滤条件缩小拉取范围
如果只需要上个季度的数据,就别拉一百万行。按时间或状态过滤,从第一次请求起就能缩小范围。
如果剩下的数据量仍然很大,可以自己切成几个时间窗口,每个窗口各跑一个游标循环。这是客户端组织工作的方式,与分页方案本身无关。
键集分页(keyset pagination)则是另一回事:它用上一页的过滤值来界定下一页。如果客户的 API 不下发游标,只提供过滤和排序,就自己构造键集:取本页最后一行的 created_at 和 id,作为下一次请求的条件。
无论哪种方式,排序都必须稳定。只按 created_at 排序是不够的:时间戳相同的两条记录可能在两次请求之间互换位置,如果它们恰好落在分页边界上,就会一行重复、一行遗漏。加上 id 作为第二排序键,两行就永远不会并列。
还有两个细节常常耗掉一个下午。一是数组在查询串里的传法并不统一:按照 OpenAPI 的说明,form 风格既可以是 ?color=blue,green,red,也可以是 ?color=blue&color=green,要确认客户的 API 接受哪种。二是很多 API 用 - 前缀表示降序,例如 sort=-created_at。
params = {
"limit": 100,
"status": "closed,resolved", # 或重复传参,取决于 API
"sort": "created_at,id", # 升序,id 用于决胜(多字段写法仅作示意)
}
过滤和排序只有在背后有数据库索引时才快。如果某个过滤条件让每次请求都明显变慢,先问客户的工程团队这个字段有没有索引,再下结论说 API“慢”。
第 5 步:分批、429 与检查点
数据拉得够多,迟早会撞上限流。规范的 API 会返回 HTTP 429 Too Many Requests,你的脚本必须把它当作等待的信号。下面是一个逐步加长等待时间的简化写法;如果客户文档规定了自己的重试策略,以文档为准。
import time, json, os
def get_with_retry(session, url, params, max_tries=6):
for attempt in range(max_tries):
resp = session.get(url, params=params)
if resp.status_code != 429:
resp.raise_for_status()
return resp.json()
time.sleep(2 ** attempt) # 依次等待 1、2、4、8……秒
raise RuntimeError("多次重试后仍返回 429")
def save_checkpoint(cursor, path="checkpoint.json"):
with open(path, "w") as f:
json.dump({"cursor": cursor}, f)
def load_checkpoint(path="checkpoint.json"):
if not os.path.exists(path):
return None
with open(path) as f:
return json.load(f).get("cursor")
这两个函数只有接入游标循环才有用。最重要的规则:批次落盘之后再保存游标。如果先保存游标,脚本又在写文件时挂掉,下次运行就会从那些根本没写进去的行之后开始。
def flush(batch, out_dir):
last_id = batch[-1]["id"]
with open(f"{out_dir}/batch_{last_id}.jsonl", "w") as f:
for row in batch:
f.write(json.dumps(row) + "\n")
save_checkpoint(last_id) # 数据完整写入之后再保存游标
def pull_all(session, url, out_dir, limit=100, batch_size=1000):
params = {"limit": limit}
cursor = load_checkpoint()
if cursor:
params["starting_after"] = cursor # 从保存的位置续跑
batch = []
while True:
page = get_with_retry(session, url, params)
items = page["items"]
batch.extend(items)
if len(batch) >= batch_size:
flush(batch, out_dir)
batch = []
if not page["has_more"] or not items:
break
params["starting_after"] = items[-1]["id"]
if batch:
flush(batch, out_dir)
假设脚本在 10,000 次请求中的第 7,000 次挂掉。文件里的游标是最近一个完整写入批次的最后一个 ID,所以下次运行会重新拉取那几页没落盘的数据,然后接着往下走,不必从头再来,也不会漏掉一行。
每个文件以该批次的最后一个 ID 命名,重跑时也不会覆盖之前的数据。
如果要反复同步,看看 API 是否支持用 ETag 或 Last-Modified 做缓存,避免重复拉取没有变化的数据。
最后检查:比较唯一 ID 的数量和写入的总行数,两者必须一致。如果不一致,就是出现了页面漂移、排序不稳定,或者重试写入了重复数据,交付数据之前必须修好。
这项技能在客户现场怎么体现?
客户不会问你懂不懂游标分页。他们会问:为什么看板比源系统少了 312 张工单?谁能在一小时内答上来——因为记了游标日志、数过唯一 ID、知道什么是页面漂移——谁就能接到下一份工作。
读 FDE 的岗位描述时,留意那些关于对接客户系统、或从第三方系统搭建数据管道的要求:这项技能每天都用在那里。
简历上不要只写“API 集成”,要具体:拉了多少条记录,用的哪种分页方式,限流怎么处理,数据完整性怎么核验。
一个从 Slack 或 Stripe 沙箱拉数据的 GitHub 小项目,带检查点和行数对账步骤,比一句笼统的描述更有说服力。
能在笔记本上跑通的脚本只是起点。客户真正检查的是:即便脚本半夜中断又重跑,行数是否仍和源系统对得上。
这篇文章对你有帮助吗?
感谢你的反馈!
7 个信源
- Everything You Need to Know About API Pagination · 2019-10-17
- Pagination in the REST API - Atlassian · 2018-10-02
- Pagination | Stripe API Reference
- Pagination | Slack Developer Docs
- Unlocking the Power of API Pagination: Best Practices and Strategies · 2023-06-06
- How to Implement Filtering and Sorting in REST APIs · 2026-01-26
- Describing Parameters - OpenAPI Guide