批量核验任务跑到一半挂了怎么办：断点续跑的设计与实现

这是接口对接系列的又一篇。上一篇讲了超时后先查后重这篇解决一个更工程化的问题一个 5000 条的批量核验任务跑到 3000 条时服务挂了/断网了/发版了怎么优雅地继续而不是从头再来从头再来的代价不只是时间已核验的 3000 条要重新计费用户会收到第二次通知账单和对账全乱。断点续跑是批量任务的标配能力但它比想象中容易做错。一、断点续跑的核心任务状态必须落库最容易想到的做法是记个进度数字——已完成 3000 条。这不够。真正的断点续跑要求任务可以随时被杀死重启后从持久化状态完整恢复这意味着要落库的不只是进度而是每一条的明细状态importsqlite3,json,time dbsqlite3.connect(batch_task.db)db.execute( CREATE TABLE IF NOT EXISTS task_items ( seq INTEGER PRIMARY KEY, -- 序号原始顺序 biz_no TEXT UNIQUE, -- 业务单号幂等键来源 payload TEXT, -- 原始请求参数 status TEXT DEFAULT pending,-- pending/done/failed/timeout result TEXT, -- 核验结果 JSON updated_at REAL ))判断你的落库设计合不合格用一个标准把进程 kill -9 之后重启系统能否从库里恢复出哪些做完了、哪些没做、哪些结果未知的完整视图。能就合格只靠内存进度就不合格。二、断点分类不同断法续法不同任务中断后重启不能无脑从第 3001 条继续——要按每条的末次状态分流defresume_task(task_id):# 三类续跑队列pending[]# 从未执行直接跑retryable[]# 执行过但失败/超时按超时纪律处理verify[]# 超时未确认先查询别重跑rowsdb.execute(SELECT seq, biz_no, status FROM task_items WHERE task_id?,(task_id,)).fetchall()forseq,biz_no,statusinrows:ifstatusdone:continue# 完成的跳过不重复计费elifstatustimeout:verify.append(seq)# 先查后重elifstatusin(failed,pending):pending.append(seq)returnpending,retryable,verify三个关键决策1.done的绝不重跑——每一条重跑都是真实计费。这就是为什么 done 状态必须在收到响应的瞬间落库而不是批量收工后统一写。2.timeout的先查询——超时是结果未知直接重跑可能重复核验。用上一篇文章讲的查询接口确认状态后再决定补跑还是标记完成。3.failed的看原因——业务拒绝不一致补跑无意义直接标终态系统异常才进重试队列且受重试预算约束。三、写入时机每条确认后立即落库断点续跑最常见的翻车是批量写状态跑完 100 条写一次进度。进程在第 99 条挂掉时前 99 条全部状态未知只能靠查询接口逐条确认——费钱又费时。正确的写入时机每一条收到响应立即 commit。defprocess_one(seq,biz_no,payload):try:resultcall_verify_api(biz_no,payload)status,res(done,result)ifresult[ok]else(failed,result)exceptrequests.Timeout:status,restimeout,None# 单条立即落库——kill -9 也不丢db.execute(UPDATE task_items SET status?, result?, updated_at? WHERE seq?,(status,json.dumps(res,ensure_asciiFalse),time.time(),seq))db.commit()SQLite 单条 commit 的性能完全够用每秒数千次量级更大再换 PostgreSQL模式不变。代价是吞吐下降——每条一次磁盘写。生产上的折衷按确认即写保证正确性把性能优化放在批量读取一次取 100 条待处理而不是批量写入上。四、发版/迁移场景任务与代码解耦批量任务经常死于发版任务跑到一半代码要更新。两个实践1. 任务数据与代码版本解耦——task_items 表里的 payload 存的是当时请求参数的完整快照而不是引用业务表的最新数据。业务数据可能已经变了续跑时用快照保证同一批的一致性。2. 版本号记录在任务元数据里db.execute(INSERT INTO task_meta (task_id, code_version, started_at) VALUES (?,?,?),(task_id,CODE_VERSION,time.time()))续跑时如果代码版本变了至少日志里能看到这个任务是 v1.3 跑了一半、v1.4 续的——出了数据口径问题知道往哪查。五、一套完整的断点续跑 Checklist□ 明细落库每条独立状态行非进度数字 □ 即时提交收到响应立即 commit非批量写 □ 断点分类pending/timeout/failed 三类分流续跑 □ timeout 先查询确认后决定补跑防重复计费 □ done 永不重跑幂等键 状态检查双保险 □ payload 快照续跑用当时的参数非最新业务数据 □ 版本记录任务元数据带代码版本可追溯 □ 恢复演练上线前真的 kill -9 一次验证恢复完整最后一条最重要——断点续跑是必须演练过才算有的能力。没被真正 kill 过的续跑逻辑等于没有。小结断点续跑 明细状态落库 即时提交 按末次状态分流恢复timeout 先查询、done 永不重跑、failed 看原因——三类断点的处理纪律payload 快照保证续跑一致性版本记录保证可追溯上线前必须 kill -9 演练一次上一篇超时之后别急着重试先查状态的接口设计模式。示例代码仓库在 GitHub搜索 nztapi-verify-skill 可找到完整实现批量场景的合规边界见官网说明https://www.nztapi.com/blog/insights/batch-identity-verification-compliance-boundary