编程 offset 分页会静默漏单:批量单据同步的游标分页、进度表与 429 退避

2026-11-21 21:34:04

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)

三个关键细节:

  1. 坏数据跳过,游标照样前进。 一条金额为负的单据卡住整个分片,只能靠人工修完再跑,其余数据全被堵在后面。
  2. 超时后先确认再重推。 确认动作本身要走业务去重键查询,不能靠「再推一次看看」。
  3. 致命错误让任务停下来。 401/403 继续循环只会刷满日志,告警 + 暂停才是正确响应。

踩坑清单

  • 总数对不上、少几百条:offset 分页期间源表有增删。
  • 重跑后出现重复单据:超时后盲目重推。
  • 越跑越慢:循环内反复查库。主数据、映射规则应该在循环外一次性加载。
  • 凌晨任务失败:和对方备份/汇总窗口撞车,需要错峰。
  • 不知道同步到哪了:进度只存在内存里。
  • 重试把对方限流越推越紧:固定间隔硬重试,改成指数退避 + 客户端令牌桶。

验证口径

同步跑完不能只看「没报错」。以下五项是对账的基本盘:

  • 行数守恒:源表条数 = 目标表条数 + 异常队列条数。
  • 金额守恒:按业务去重键分组汇总,源与目标的金额差值为 0。
  • 中断可续:人为 kill 进程后重跑,已完成分片全部跳过,未完成分片从 last_id 接上。
  • 幂等验证:同一任务连跑两遍,第二遍零新增。
  • 限流友好:整个同步窗口内,对方无 429、无超时告警。

行数守恒和金额守恒能抓出 offset 分页的静默漏单;幂等验证能抓出结果未知时的盲目重推。这两类问题都不会在日志里留下痕迹,只能靠对账发现。

复制全文 生成海报 接口对接 MySQL Python 对账

推荐文章

程序员茄子在线接单