# 只靠 ETag，客户的 API 数据同步不可靠

> 要处理重复记录、发现已删除数据，ETag 还得配合时间水位线、分页游标和定期全量对账。

原文: https://fdetimes.net/zh/guides/etag-incremental-sync-customer-api/

在 GitHub 上，返回 304 Not Modified 的条件请求不计入主速率限制。但 GitHub 自己的文档写得很明确：只有端点真的返回 304，才能省下时间和配额。

到了客户现场，这正是第一件要确认的事。你要对接的 API 可能是工单系统、CRM，也可能是某个人五年前写的内部服务，它也许从来没返回过一次 304。

很多部署项目都从同一项任务开始：定期拉取客户数据，既不耗尽对方的配额，也不漏掉任何一条记录。

本指南搭建一个两层的同步方案。第一层用 ETag 以几乎为零的代价询问“有没有变化？”。第二层用 `updated_since` 这类时间水位线，配合分页游标，精确拉取发生变化的数据。最后是定期对账，这一步很多人会忘。

## 开始之前需要准备什么？

你需要 `curl`、装有 `requests` 库的 Python 3，以及任意一个可供试验的 GitHub 公开仓库。为便于阅读，文中的 Python 片段做了精简，没有重试、退避和网络错误处理，不要直接粘贴到生产环境。

先说 ETag 的概念。MDN 将它描述为资源某个特定版本的唯一标识符，而且是一个不透明的字符串：客户端不需要知道其中的内容。

客户端保存这个字符串，下次请求时带上它，询问服务器资源是否有变化。如果没有变化，服务器返回 304 Not Modified，而不是重新发送完整的响应体，客户端继续使用本地保存的副本。

## 第 1 步：检查服务器是否返回 ETag

```bash
curl -i https://api.github.com/repos/OWNER/REPO
```

**检查：**响应头中有一行 `etag`。原样复制这个值，包括引号和可能存在的前缀。由于这个字符串是不透明的，你不需要理解它，也不应该尝试自己构造。

## 第 2 步：带回 ETag，预期得到 304

```bash
curl -i https://api.github.com/repos/OWNER/REPO \
  -H 'If-None-Match: <粘贴第 1 步得到的 etag 原值>'
```

**检查：**状态行是 `304`，响应体为空。按照 MDN 的说明，GET 或 HEAD 请求的条件不成立时，服务器必须返回 304，并附带它在 200 响应中会发送的部分响应头，其中包括 ETag。所以即使没有新数据，客户端照样能读到 ETag。

比较规则也值得弄清楚。只有当服务器的 ETag 与客户端列出的所有 ETag 都不同时，If-None-Match 才算成立，也就是返回新内容。这里采用弱比较：内容等价的两个版本被视为相同。因此，304 并不保证两边逐字节一致。

## 第 3 步：按 URL 保存 ETag

按 GitHub 描述的流程，你保存一次响应中的 etag，在下次请求同一 URL 时放进 `if-none-match` 请求头。每个 ETag 只对应一个 URL，所以存储的键也必须是 URL，包括查询字符串。

```python
# 为演示做了精简：没有重试、退避和错误处理
import requests

def fetch(url, etags):
    headers = {}
    if url in etags:
        headers["If-None-Match"] = etags[url]
    r = requests.get(url, headers=headers, timeout=30)
    if r.status_code == 304:
        return None              # 未变化，使用本地保存的副本
    r.raise_for_status()
    if "ETag" in r.headers:
        etags[url] = r.headers["ETag"]
    return r.json()
```

**检查：**用同一个 URL 连续调用两次 `fetch`，第二次必须返回 `None`。假设每 5 分钟轮询一次某个端点，一天就是 288 次请求。如果数据一天只变化 20 次，其余 268 次请求都可以以 304 结束；在 GitHub 上，这些请求不占用主速率限制。

## 为什么只有 ETag 还不够？

ETag 只回答一个问题：“这个资源变了没有？”面对一个有 100,000 条订单的列表，得到“变了”的回答之后，如果还得重新下载全部 100,000 条，这个回答就没多大用处。你还需要问“哪些变了？”，时间水位线就是为回答这个问题而存在的。

Zendesk 提供了一个真实的例子。使用它的增量导出 API 时，你提供一个起始时间，API 返回从该时间起创建或修改过的全部条目。

“从该时间起”意味着恰好在边界时刻更新的记录会在两轮同步中都出现。如果水位线是 10:00:00，而某张工单恰好在 10:00:00 被编辑，那么下一轮还会拿到这张工单。

**要点:** 好的同步方案照样会遇到重复记录，但无论运行多少次，结果都一样。

## 第 4 步：把水位线和分页游标分开

这两个概念经常被混淆。Stripe 按对象 ID 分页（`starting_after`），并带有 `has_more` 标志；标志为 `false` 时，说明已到列表末尾。Zendesk 在游标模式下，每页都会返回供下次请求使用的游标，而 `end_of_stream` 属性告诉你何时停止翻页。

游标负责在一轮同步中走完所有页面，水位线决定下一轮从哪里开始。下面的代码针对一个假设的客户 API，参数名和字段名仅为示例：

```python
# 假设的 API：GET /v1/orders?updated_since=...&cursor=...
# 返回 {"items": [...], "next_cursor": "...", "has_more": true}
def sync_orders(base, watermark, db):
    newest = watermark
    cursor = None
    while True:
        params = {"updated_since": watermark}
        if cursor:
            params["cursor"] = cursor
        page = requests.get(f"{base}/v1/orders", params=params,
                            timeout=30).json()
        for item in page["items"]:
            db.upsert(item["id"], item)      # 按 id 覆盖写入
            newest = max(newest, item["updated_at"])
        if not page["has_more"]:
            break
        cursor = page["next_cursor"]
    return newest    # 循环全部结束后才保存新的水位线
```

这段代码有两个选择，写正式实现时值得保留。按 `id` 执行 upsert，时间戳边界上的重复记录就不会造成影响。

新水位线取自服务器返回的数据，而不是本机时钟，并且只在整轮同步成功后才写入。如果任务在第 7 页中断，下一轮会从旧边界重新开始，而不是跳过前六页。

**检查：**用同一个水位线运行两次 `sync_orders`，存储中的记录数必须保持不变。

## 第 5 步：安排对账，处理已删除记录

记录被删除后，就不再有供水位线识别的 `updated_at`。Zendesk 表示，其增量导出仍可能包含已删除的记录，但工单一旦被永久删除，只会保留一条精简记录 90 天。如果你的任务停摆超过这个时间，删除的痕迹也会随之消失。

稳妥的做法是定期从客户 API 拉取完整的 ID 列表，与本地存储比对，标记已不存在的 ID。这一步开销很大，要控制频率，比如每晚或每周一次，具体取决于客户能容忍数据滞后多久。

## 最常见的错误

最常见的错误是默认每个端点都支持 304。在把 ETag 纳入设计之前，先对客户自己的 API 重做一遍第 2 步。第二个错误是把 304 当作数据逐字节一致的证明，而实际采用的是弱比较。第三个错误是每处理完一页就推进水位线，而不是等整轮同步结束。

还有一个：在没必要的时候轮询。GitHub 建议尽可能订阅 webhook，而不是轮询 API；如果必须轮询，就按固定的时间表进行。客户系统提供 webhook 时，用它来获知变化，把增量同步作为兜底。

## 在客户现场，这项技能用在哪里？

和客户合作的第一周，就直接问三个问题：“你们的 API 返回 ETag 吗？能按更新时间过滤吗？删除操作怎么通知？”尽早问清楚，就不会在演示当天遇到数据管道耗光配额的情况。

阅读前线部署工程师（FDE）的招聘启事时，如果看到对接客户系统、搭建数据管道之类的表述，就准备一个可以展开讲的增量同步案例。简历上别只写“API 集成”。

要讲清楚你如何处理重复记录、分页和已删除记录，有真实数字更好，比如以 304 结束的请求占比。

在系统设计面试中，别停在“用 `updated_since`”这一步。主动追问自己“已删除的记录怎么办？”，再说明你的对账安排。

**本周动手试试:**

- 对一个 GitHub 公开仓库运行本指南中的两条 curl 命令，确认第二条返回 304。
- 选一个客户或公司在用的 API，把它返回的 ETag 发回去，记录它是否返回过 304。
- 写一个按 id 执行 upsert 的同步函数，用同一个水位线连续运行两次，然后检查存储中的记录数有没有变化。

## 信源

- [HTTP conditional requests - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests)

- [If-None-Match header - MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-None-Match)

- [Best practices for using the REST API - GitHub Docs](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api)

- [Using the Incremental Exports API - Zendesk Developer Documentation](https://developer.zendesk.com/documentation/api-basics/working-with-data/using-the-incremental-export-api/)

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