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

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

原文: https://fdetimes.net/zh/guides/paginate-million-records-client-api/

一个系统有 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` 是占位字段名，请对照真实响应核实。

```python
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 行，于是有五行返回了两次。如果是记录被删除而不是新增，情况正好相反，会跳过五行。

**要点:** 只有数据静止不动时，offset 才安全。而客户的生产环境很少静止不动。

## 第 3 步：等服务器说停才停的游标循环

游标能避免页面漂移，因为它标记的是“在这条记录之后”，而不是“在第 N 个位置之后”。Stripe 用本页最后一个对象的 ID 作为 `starting_after`。下面的代码沿用 Stripe 的模式，`items` 是占位字段名。

```python
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`。

```python
params = {
    "limit": 100,
    "status": "closed,resolved",   # 或重复传参，取决于 API
    "sort": "created_at,id",       # 升序，id 用于决胜（多字段写法仅作示意）
}
```

过滤和排序只有在背后有数据库索引时才快。如果某个过滤条件让每次请求都明显变慢，先问客户的工程团队这个字段有没有索引，再下结论说 API“慢”。

## 第 5 步：分批、429 与检查点

数据拉得够多，迟早会撞上限流。规范的 API 会返回 HTTP 429 Too Many Requests，你的脚本必须把它当作等待的信号。下面是一个逐步加长等待时间的简化写法；如果客户文档规定了自己的重试策略，以文档为准。

```python
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")
```

这两个函数只有接入游标循环才有用。最重要的规则：批次落盘之后再保存游标。如果先保存游标，脚本又在写文件时挂掉，下次运行就会从那些根本没写进去的行之后开始。

```python
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 小项目，带检查点和行数对账步骤，比一句笼统的描述更有说服力。

能在笔记本上跑通的脚本只是起点。客户真正检查的是：即便脚本半夜中断又重跑，行数是否仍和源系统对得上。

**本周动手试试:**

- 打开 Stripe、Slack 和 Confluence 的分页文档，把各自的翻页参数、limit 上限和停止信号整理进一张表。
- 写一个 pull_all() 函数：显式设置 limit，遇到 429 重试，每批写入磁盘后保存游标；然后在中途杀掉进程再重跑，看唯一 ID 数是否对得上。
- 在本地表上复现页面漂移：一边按 offset 读取，一边插入新行，然后统计重复的 ID。

## 信源

- [Everything You Need to Know About API Pagination](https://nordicapis.com/everything-you-need-to-know-about-api-pagination/)

- [Pagination in the REST API - Atlassian](https://developer.atlassian.com/server/confluence/pagination-in-the-rest-api/)

- [Pagination | Stripe API Reference](https://docs.stripe.com/api/pagination)

- [Pagination | Slack Developer Docs](https://docs.slack.dev/apis/web-api/pagination)

- [Unlocking the Power of API Pagination: Best Practices and Strategies](https://dev.to/pragativerma18/unlocking-the-power-of-api-pagination-best-practices-and-strategies-4b49)

- [How to Implement Filtering and Sorting in REST APIs](https://oneuptime.com/blog/post/2026-01-26-rest-api-filtering-sorting/view)

- [Describing Parameters - OpenAPI Guide](https://swagger.io/docs/specification/describing-parameters/)
