FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

百万条记录、一万次请求,一行都不能丢

offset 分页翻到末页几乎要扫全表,游标、键集和检查点让大批量拉取又快又不会悄悄重复。

分享微博

要点速览

  • offset 写起来简单,但 offset 越大越慢;拉取过程中数据一变,还可能重复或跳过若干行。数据量大时优先用游标。
  • 始终显式设置 limit,排序时加上 id 这类决胜字段,等服务器发出结束信号再停,绝不自己数页数。
  • 批次落盘之后再保存游标,并处理 HTTP 429。这样大批量拉取中断后才能续跑,一行不丢。
大数字图表:拉取 1,000,000 条记录,如果不设置 limit(API 默认每页 10 行,Stripe 即是如此),需要 100,000 次请求;设置 limit=100 则需要 10,000 次。图中两条横条的长度比为 10:1。
对于 1,000,000 条记录,忘记设置 limit 参数会让请求次数增加到十倍。来源:文中计算,基于 Stripe 默认每页 10 行。

一个系统有 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 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力写客户集成时,假设每个请求都会到两次超时后重试一次,就可能让客户被扣两次款;Stripe 的建议是用幂等键让服务器认出重发的请求。