只靠 ETag,客户的 API 数据同步不可靠
要处理重复记录、发现已删除数据,ETag 还得配合时间水位线、分页游标和定期全量对账。
要点速览
- 只有端点真正支持 304,它才能帮你省下请求,所以写代码前先用 curl 测一遍。
- “从某个时间点起”的时间戳会让恰好落在边界上的记录重复返回,因此要按 id 覆盖写入。
- 水位线发现不了已删除的记录,还需要定期做一次全量对账。
在 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
curl -i https://api.github.com/repos/OWNER/REPO
**检查:**响应头中有一行 etag。原样复制这个值,包括引号和可能存在的前缀。由于这个字符串是不透明的,你不需要理解它,也不应该尝试自己构造。
第 2 步:带回 ETag,预期得到 304
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,包括查询字符串。
# 为演示做了精简:没有重试、退避和错误处理
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,参数名和字段名仅为示例:
# 假设的 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”这一步。主动追问自己“已删除的记录怎么办?”,再说明你的对账安排。
这篇文章对你有帮助吗?
感谢你的反馈!