incremental-fetch

增量获取

构建永不丢失进度、也不会重新获取已有数据的数据管道。

双水位线模式

跟踪两个游标，以同时支持向前和向后获取：

水位线	用途	API 参数
newest_id	获取自上次运行以来的新数据	since_id
oldest_id	回填较早的数据	until_id

单个水位线只能向前获取。两个水位线则可以：

• 常规运行：获取新数据（自 newest_id 起）
• 回填运行：获取较早的数据（截至 oldest_id）
• 不重叠，不遗漏

关键：数据与水位线的保存

这是两个不同的操作，保存时机也不同：

内容	保存时机	原因
数据记录	每获取一页后	提高韧性：如果在第 47 页中断？保留前 46 页
水位线	每次运行结束时保存一次	保证正确性：只有完整成功后才提交进度

fetch page 1 → save records → fetch page 2 → save records → ... → update watermarks

工作流决策树

First run (no watermarks)?
├── YES → Full fetch (no since_id, no until_id)
└── NO → Backfill flag set?
    ├── YES → Backfill mode (until_id = oldest_id)
    └── NO → Update mode (since_id = newest_id)

实现检查清单

1. 数据库：创建 ingestion_state 表（参见 patterns.md）
2. 获取循环：每获取一页 API 数据后立即插入记录
3. 水位线跟踪：跟踪本次运行中看到的最新和最旧 ID
4. 水位线更新：仅在运行成功结束时保存一次水位线
5. 重试：使用带抖动的指数退避
6. 速率限制：等待限制重置，或跳过并记录以供下次运行处理

分页类型

此模式最适合基于 ID 的分页（可比较的数字 ID）。对于其他分页类型：

类型	调整方式
游标／令牌	存储游标字符串，而不是 ID；无法进行数值比较
时间戳	使用 last_timestamp 列；按日期比较
偏移量／限制	存储页码；从上次保存的页面继续

有关模式和代码示例，请参阅 references/patterns.md。

注意事项

• 仅在完全成功后保存水位线。 如果进程在运行中途崩溃，由于水位线未保存，下次运行会重新获取数据并从头去重——不会丢失数据，但可能会比较慢。在运行中途保存水位线会造成永久性遗漏。
• 最新 ID 不一定是数值最大的 ID。 某些 API 返回的 ID 不会单调递增（例如受时钟漂移影响的雪花 ID）。始终根据 API 自身的排序保证进行比较，而不要进行数值比较。
• 回填模式不得覆盖 newest_id。 回填运行会向前扩展历史记录；它只应更新 oldest_id。回填期间覆盖 newest_id 会导致下一次向前更新时重复获取数据。
• 不同 API 的速率限制标头各不相同。 Twitter 使用 x-rate-limit-reset；其他 API 则使用 Retry-After。实现等待逻辑前，请检查相应 API 的响应标头。