offset 分页会静默漏单:批量单据同步的游标分页、进度表与 429 退避
场景
跨系统推单据(订单、出库单、发票)通常发生在三个时机:上线前的存量迁移、按天/按小时的批量汇总、历史单据补推。
约束很硬:
- 单次请求超时上限一般 30 秒到 2 分钟,几十万条不可能一次推完;
- 超时之后不知道对方处理了多少条——可能全回滚,也可能处理了一半;
- 进程中途被 kill,如果没有落地的进度,就不知道从哪继续。
这两点直接导致重复和丢数据。设计目标只有一句话:任何时间点中断,都能从中断处继续,最终结果与一次跑完一致。
三种分页策略
| 策略 | 典型写法 | 漏数据风险 | 重复风险 | 适用场景 |
|---|---|---|---|---|
| offset 分页 | LIMIT 1000 OFFSET n | 高 | 低 | 源表完全冻结的一次性迁移 |
| 时间窗分页 | updated_at >= t1 AND updated_at < t2 | 中(窗口边界) | 低 | 有可靠修改时间戳的表 |
| 主键游标分页 | id > :cursor ORDER BY id LIMIT 1000 | 低 | 中(修改类数据需配合时间戳) | 默认选择,配合幂等键兜底 |
offset 漏数据不是偶发,是机制性的:取完第一页之后,源表删掉一条记录,第二页整体前移一条,最后一页的最后一条就被跳过了。整个过程不抛异常、不报错,只有对账时才发现少了几百条。
主键游标的取数语句:
SELECT id, order_no, customer_code, amount, status, updated_at
FROM sale_order
WHERE id > :last_id
ORDER BY id
LIMIT 1000;
游标分页的重复风险来自「修改类数据」:一条记录第一次被读到、第二次被更新,主键游标不会再回到它。所以存量迁移阶段如果期间数据还会变,要拆成两条线跑——主键游标抓新增,修改时间戳抓变更,最后按业务去重键(如 order_no)合并。两条线的进度分别记录,互不干扰。
并发与限流:参数只是起点
以下数值是经验值,不是对方系统的官方容量承诺,必须实测:
- 批量大小 100–500 条;涉及金额、需要对方做事务的接口取小值;
- 并发请求数 2–4,老系统从 2 起步;
- 重试间隔指数退避 1s / 2s / 4s / 8s;
- 单批超时 30s,超时后进入「结果未知」状态,走确认逻辑而不是重推。
先拿 200 条做一次小批量压测,看对方响应时间和错误率,再决定最终批量。客户端自己加令牌桶限流——否则重试叠加会把实际 QPS 顶到阈值以上,越重试越被限。
进度必须落库
进度放在内存或本地文件里,进程一挂就归零,重跑要么全量重来,要么不知道从哪接。进度表结构:
CREATE TABLE sync_progress (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
task_name VARCHAR(64) NOT NULL COMMENT '任务名,如 order_to_mes',
shard_key VARCHAR(128) NOT NULL COMMENT '分片标识,如游标段起点',
status VARCHAR(16) NOT NULL COMMENT 'pending/done/unknown/failed',
last_id BIGINT NULL COMMENT '该分片已确认同步到的主键',
retry_count INT NOT NULL DEFAULT 0,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_task_shard (task_name, shard_key)
);
运行逻辑按 status 分支:
done:跳过;pending:正常处理;unknown(请求超时、结果未确认):先按业务去重键确认目标侧是否存在,存在则标done,不存在才重推;failed:等人工介入。
uk_task_shard 这个唯一键是幂等的基础,重跑同一个分片时更新而不是插入新行。
错误分级
把所有异常都当「重试三次」处理,结果通常是:能重试的把对方打挂,不能重试的把队列堵死。
| 类别 | 例子 | 处理方式 |
|---|---|---|
| 可重试·临时性 | 网络超时、连接池耗尽、对方限流(429) | 指数退避,同任务不超过 3 次(经验值) |
| 可重试·结果未知 | 请求超时但对方可能已成功 | 先按业务去重键查询确认,再决定重推或跳过,禁止盲目重推 |
| 不可重试·数据问题 | 字段超长、必填缺失、金额为负、主数据不存在 | 进异常队列,人工修复后单独重推 |
| 不可重试·结构性 | 参数格式错误、鉴权失效(401/403) | 立即告警并暂停任务 |
「结果未知」是最容易被写错的一类。HTTP 超时只说明客户端没等到响应,不代表对方没写库。这种情况下重推就是重复单据的直接来源。
Python 分片骨架
to_target / confirm_order_exists / save_to_dead_queue 需按各自业务实现,下面是控制流示意:
import time
import requests
TARGET_URL = "https://target.example.com/api/orders/batch"
TIMEOUT = 30
MAX_RETRY = 3 # 经验值,可按对方限流强度调整
BATCH = 200 # 经验值,压测后再放大到 500
BACKOFF = [1, 2, 4, 8]
class FatalError(Exception):
pass
def push_batch(task_name, shard_key, cursor, rows):
"""返回推进后的游标。数据问题不回退游标。"""
attempt = 0
while True:
try:
resp = requests.post(TARGET_URL, json=rows, timeout=TIMEOUT)
except requests.Timeout:
# 结果未知:先确认对方是否已经写入
if confirm_order_exists(rows):
return rows[-1]["id"]
if attempt >= MAX_RETRY:
raise
time.sleep(BACKOFF[min(attempt, len(BACKOFF) - 1)])
attempt += 1
continue
if resp.status_code == 200:
return rows[-1]["id"]
if resp.status_code == 429 or resp.status_code >= 500:
if attempt >= MAX_RETRY:
raise
time.sleep(BACKOFF[min(attempt, len(BACKOFF) - 1)])
attempt += 1
continue
if resp.status_code in (401, 403):
raise FatalError(f"auth failed: {resp.status_code}")
# 其余 4xx 视为数据问题:进异常队列,游标照常前进
save_to_dead_queue(rows, resp.text)
return rows[-1]["id"]
def run(task_name, shard_key, start_id):
cursor = start_id
while True:
rows = fetch_source(cursor, BATCH) # id > cursor ORDER BY id LIMIT BATCH
if not rows:
mark_done(task_name, shard_key, cursor)
return
cursor = push_batch(task_name, shard_key, cursor, rows)
save_progress(task_name, shard_key, cursor)
三个关键细节:
- 坏数据跳过,游标照样前进。 一条金额为负的单据卡住整个分片,只能靠人工修完再跑,其余数据全被堵在后面。
- 超时后先确认再重推。 确认动作本身要走业务去重键查询,不能靠「再推一次看看」。
- 致命错误让任务停下来。 401/403 继续循环只会刷满日志,告警 + 暂停才是正确响应。
踩坑清单
- 总数对不上、少几百条:offset 分页期间源表有增删。
- 重跑后出现重复单据:超时后盲目重推。
- 越跑越慢:循环内反复查库。主数据、映射规则应该在循环外一次性加载。
- 凌晨任务失败:和对方备份/汇总窗口撞车,需要错峰。
- 不知道同步到哪了:进度只存在内存里。
- 重试把对方限流越推越紧:固定间隔硬重试,改成指数退避 + 客户端令牌桶。
验证口径
同步跑完不能只看「没报错」。以下五项是对账的基本盘:
- 行数守恒:源表条数 = 目标表条数 + 异常队列条数。
- 金额守恒:按业务去重键分组汇总,源与目标的金额差值为 0。
- 中断可续:人为 kill 进程后重跑,已完成分片全部跳过,未完成分片从
last_id接上。 - 幂等验证:同一任务连跑两遍,第二遍零新增。
- 限流友好:整个同步窗口内,对方无 429、无超时告警。
行数守恒和金额守恒能抓出 offset 分页的静默漏单;幂等验证能抓出结果未知时的盲目重推。这两类问题都不会在日志里留下痕迹,只能靠对账发现。