淘宝订单 API 抓数
及补偿指南

开始之前 · 零基础先读

这一节不讲代码。看完你会明白：一笔淘宝订单是怎么进到我们库里的、为什么有两张表、以及为什么「抓到了」和「抓全了」是两回事。

先跟着一笔订单走一遍

假设今天 14:32 有位顾客在「kuyura可悠然旗舰店」下了一笔订单：

两张表，用大白话解释

130 秒速览与术语表

赶时间就记住这一节：一张职责表 + 一个黄金规则。

先记住这 14 个词

2双表架构与数据链路

这一节把图 0-1 展开成工程细节：三条淘宝 API、两条 MQ 路由、两个消费者、以及五个 Job 的新老关系。

2.1 用到的三条淘宝 API

2.2 MQ 路由与消费者

exchange: thirdhub_shelve (topic)

taobao.tradesold.{sellerId}          ← 主抓单/补偿重放，订单消息      → 下游写【增量表】
self.increment.tradesold.taobao.*    ← needFullInfo=true 时附带        → self 消费者逐单调 fullinfo
fullinfo.tradesold.taobao.*          ← fullinfo 结果                  → 下游写【全量表】(+ 订单快照)复制

三条路由都不在本仓库落库——真正写 Mongo 的消费者部署在其他服务上。所以任何补偿 Job 的日志里「补偿数量 N」指的都是成功推送了 N 条消息，不等于已落库；最终以表内 count 为准。

2.3 五个 Job 的新老关系

3主抓单与水位机制

主抓单是唯一的新单入口。它没有 startTime/endTime 参数——时间完全由每家店的水位决定，这也是它「自动无缝衔接」和「某些坑」的共同根源。

3.1 一轮执行发生了什么

对每家开启抓单的店铺（并行 shopThreadNum 路）：
  startTime = 水位(nextScheduleTime) − backSeconds      // 回看防漏
  endTime   = 水位 + incrementSeconds                    // 本轮抓到这
  if endTime > now: endTime = now                       // 不允许抓未来
  按 intervalSeconds 切片 → 每片: count → 按页拉单 → 发 MQ(增量路由 + self路由)
  本店全部成功 → 水位推进到 endTime；任何一步失败 → 水位不动，下轮重来复制

3.2 参数全解

3.3 日志怎么看

[店铺名]:开始执行:[2026-10-20T18:26:40]-[2026-10-20T19:11:40]   ← 本轮窗口（起=回看点，止=新水位）
[店铺名]:执行:[...], api总数: 951                              ← 该切片接口返回单量
[店铺名]:在:[起]-[止]时间内, api总数: N, 推送总数: M ==> true    ← 一轮汇总，false 即有切片推送失败复制

看到窗口终点离当前时间越来越近 = 在追平；一直停在同一个时间 = 水位卡住（多半有切片持续失败，查该店铺报错）。

4补偿体系：五个 Job 的分工

三个现行补偿 Job 各管一段，参数结构相似但默认值和坑不同。逐一说明。

4.1 TaobaoIncrementCountCompensateJobHandler（补增量表）

4.2 TaobaoIncrementFullInfoOrderJobHandler（补全量表）

4.3 TaobaoIncrementStatusCompensateJobHandler（刷订单状态）

5生产配置：排期与参数

以「每天凌晨 01:00 前前一天订单必须齐」为 SLA 设计的排期。xxl-job 用 Quartz 六位 cron（秒 分 时 日 月 周）。

5.1 推荐排期总表

5.2 xxl-job 侧设置

• 主抓单：阻塞策略选「单机串行」，任务超时设 0（不限）；避免上轮未完下轮触发把水位卡死。
• 补偿 Job 之间不要并发：00:30/00:40 错峰 10 分钟，白天补数时先停主抓单或错开时段，防止抢接口配额（批量接口 500 的诱因之一就是并发限流）。
• 大促日预案：主抓单 cron 临时 0 0/5 * * * ?（incrementSeconds 保持 1200，净追 5 分钟/轮）；00:30 的全量兜底按店铺拆 + intervalMinute=15；00:55 核对发现缺口立即按第 6 节补，不要等第二天。

5.3 这套排期能保证什么、不能保证什么

6补数手册

按「缺什么」走对应分支。所有 Job 幂等，重复跑安全；时间参数一律北京时间；同一天只跑一个补偿 Job，不要并发。

6.1 场景 A：补增量表

识别：接口数量 > 增量表（Count 补偿日志「时间段异常， api数量:x, db数量:y」，或核对脚本报增量缺）。

Job:  TaobaoIncrementCountCompensateJobHandler
按天跑（缺口大再拆半天）：
{"startTime":"2026-10-18 00:00:00","endTime":"2026-10-19 00:00:00","intervalMinute":60,"sleep":3000}复制

• 日志判读：先「api数量/db数量」整段对账 → 「时间段异常」切片 → 「开始补偿」→ 最后「补偿后, api数量:x, db数量:y」。
• 该 Job 不能按店铺过滤，全店跑；某店持续「开始补偿但 db=0」说明下游没落该类型，别重复跑，先查消费者。

6.2 场景 B：补全量表

识别：增量 = 全量 不成立且「增量 > 全量」。

Job:  TaobaoIncrementFullInfoOrderJobHandler
小缺口（<1000 单）整段跑：
{"startTime":"2026-10-16 00:00:00","endTime":"2026-10-17 00:00:00","intervalMinute":60,"sleep":1000}

大缺口（>5000 单 或 含大促小时）按店铺拆 + 15 分钟切片：
{"startTime":"2026-10-20 00:00:00","endTime":"2026-10-21 00:00:00","intervalMinute":15,"sleep":1000,"sellerId":"808734231"}复制

• 必跑前置：对应日期的增量表已齐（场景 A 先做）。
• 游标丢失（-5）报错时：重跑安全、幂等；若卡在某个大促小时反复失败，先算出该小时具体缺的 tid（第 7 节差集脚本），走场景 C 单号直补，让「数量相等」后该小时即被跳过。
• 它永远返回 SUCCESS——验收只看 count。

6.3 场景 C：单号直补（列表接口碰不到的单）

识别：订单号在两张表都查不到，但菜鸟单据表里有（taobao_wlb_wms_cainiao_bill.trade.orderSourceCodes 包含该单号）；或核对时差集算出了具体 tid。

单笔：
POST /api/order/fullInfo
{"tid":"3316521615004026973","sellerId":"2206567129287"}

批量（每批 50~100，body 为数组）：
POST /api/order/fullInfo/list
[{"tid":"…","sellerId":"…"},{"tid":"…","sellerId":"…"}]复制

6.4 场景 D：老单晚到 / 历史缺口回涨

识别：已经清零的历史日期，几天后核对又出现小缺口（如 10-16 从 12 单回涨到 153 单）——modified 抓单把「创建早、最近才修改」的单补进了增量表。

Job:  TaobaoIncrementFullInfoOrderJobHandler
直接按 created 覆盖回涨日期重跑（老单会被一并对上）：
{"startTime":"2026-10-16 00:00:00","endTime":"2026-10-17 00:00:00","intervalMinute":60,"sleep":1000}复制

日常预防：每周手动跑一次「最近 7 天」窗口（intervalMinute=60），比每日只兜「昨天」更能收敛这类回涨；根治方案见 9.2。

6.5 补完必验收

回到第 7 节的核对方法，目标口径：每个北京天 × 每个 sellerId，增量表 count = 全量表 count。差集为空即收工。

7核对与验收

唯一可信的验收方式：直接查 Mongo 对 count。这里给出可直接复用的口径与脚本。

7.1 时区规则（最容易踩的坑）

7.2 逐日核对脚本（北京天 × 店铺）

# 以卖家 808734231、北京 10-20 为例（窗口 = 库内 [10-19 16:00, 10-20 16:00)）
inc = db.tradesold_taobao_increment.count_documents({
  "sellerId": 808734231,
  "trade.created": {"$gte": ISODate("2026-10-19T16:00:00Z"),
                    "$lt":  ISODate("2026-10-20T16:00:00Z")}})
full = db.tradesold_taobao.count_documents({
  "sellerId": 808734231,
  "trade.created": {"$gte": ISODate("2026-10-19T16:00:00Z"),
                    "$lt":  ISODate("2026-10-20T16:00:00Z")}})
# inc == full 即齐；inc > full 走场景 B 补全量复制

7.3 差集定位（找出具体缺哪些单号）

ids = [x["_id"] for x in db.tradesold_taobao_increment.find(
  {"sellerId": 808734231,
   "trade.created": {"$gte": ISODate("2026-10-19T16:00:00Z"),
                     "$lt":  ISODate("2026-10-20T16:00:00Z")}}, {"_id": 1})]
have = set(x["_id"] for x in db.tradesold_taobao.find(
  {"_id": {"$in": ids}}, {"_id": 1}))
missing = [t for t in ids if t not in have]   # 具体缺失 tid，走场景 C 直补复制

大促小时（单小时 >1 万）建议加 maxTimeMS 并分批 $in，避免全表扫描超时。

7.4 在售店铺 sellerId 对照（2026-10 实测）

店铺增减以 tradesold_snapshot_shop_config / admin 配置为准；上表是 2026-10 大促期间有单量的主集合。

8排障手册

按症状索引。每条都来自 2026-10 的真实事件，附判据与处置。

8.1 症状速查表

8.2 Mongo 游标丢失（-5）详解

两个 Job 先后中招（10-19 Status 补偿第 5 页、10-21 FullInfo 补偿 10-15 20:00 大促小时的第 8 页）。共同点：分页查询发出后 1 秒内失败，说明游标刚建就被服务端判不存在——环境问题而非代码逻辑错误。让 DBA 查对应时段 mongos / shard 日志（restart、stepDown、moveChunk）可坐实具体诱因。

8.3 批量接口 500 事件复盘（2026-10-19）

8.4 四类漏单：只有一类能被自动兜住

8.5 2026-10 事件时间线（供复盘对照）

9已知局限与根治建议

现行体系的三处结构性短板与对应的改造方向，按投入产出排序。

10FAQ 16 问

按提问频率排列，答案尽量一句话给结论。

11速查卡

打印贴工位。全链路只此三步：核对 → 补 → 验收。