号码状态查询批量任务：进度停在 42% 之后
两万条号码的手机号状态查询任务跑到 42% 不动，业务方在群里问还要多久，值班同学打开后台只看到一个百分比。提交那一刻该拿回什么、进度为什么不匀速、停住先查哪三件事，这篇按链路顺序讲。
🎁 免费试用手机号码状态查询 API
直连三网运营商 · 准确率 ≥99.9% · 支持携号转网识别 · 按次计费即买即用
上午十点，业务方在群里贴了一张截图：两万条号码的查询任务跑到 42% 就不动了，等了四十分钟还是这个数。运营问了一句还要多久。值班同学打开后台，发现那个页面只给了一个百分比，没有提交时间，没有分片详情，也没有失败条数。他能做的只有刷新页面。
这种只给进度条的后台，说明链路少了一段：批量任务的回执没被当成交付物做出来。进度是个观感指标，回执才是能拿去对账的东西。
提交号码清单之后，第一件要拿到的是批次号，后面的查询、重试、对账都靠它串起来。除批次号，回执里至少要有受理时间、本批条数、预计完成窗口。有了完成窗口，业务方问还要多久时，值班同学给的就是一个区间，而不是「快了」。
有的链路把回执做成同步返回，有的要靠轮询拉取或者等回调。两种都能用，但约定要写进集成文档：多久调一次、一次拉多少、什么状态算终态。轮询间隔只写 10 秒的团队，常在高峰期把自己的监控打满，这只影响自己，不影响接口。
拉回执时建议用游标翻页，别用页码。任务进行中，页码方式会因为新结果插入而重复或者漏条，游标的位置是稳定的，重试也安全。
进度忽快忽慢，多半不是接口不稳定，而是任务结构本身不均匀。号码按分片并行下发，每个分片里的号码状态不一样：空号、不在网这类往往更快出结论，欠费、通话中这类可能要等状态稳定。分片陆续回报，进度就会跳着走。
另一种情况是进度长时间不动，看着像卡死，其实在等落库。结果已经全部返回，进度条却停在某个数字上，通常是写库这一段在排队。判断方法是看回执条数是否已经等于提交条数，如果相等，问题只在展示层。
第一件，确认任务在不在跑。看同批次其它分片有没有回报，如果全部没动静，多半是队列积压，任务排在了别的批次后面。批量任务重构时怎么把异步链路拆开，可以参考订单系统接入号码状态查询：一次批量任务的重构。
第二件，看有没有分片在重试。部分失败后自动重试是正常的，但重试中的分片会让进度原地打转。这时要抓的是错误码分布，而不是进度数字：限流类错误会自己恢复，参数或鉴权类错误不会，得停下来改。
第三件，看落库环节。回执条数已经到齐，进度却没更新，问题就在结果写入这一段，通常是批量写入排队或者慢查询，跟查询接口已经没有关系。
三件事的顺序别反了。一上来就换密钥、加重试的，往往把原本只是排队的任务变成真失败。
任务跑完不代表结束，收尾要把三类数字分开统计：成功、失败、取不到结论。只留成功数，第二天再看这批结果时，就分不清那些没落库的号码是处理了还是漏了。
对账的四个动作是：提交条数对上名单行数，差在哪里要能说清；三类结果分别计数；失败条目带上错误码分布；最后记下这批结论写进了哪张表、给谁用。回执的字段含义、错误码分类与计量方式以商品详情页的文档为准，内部对账模板只引用字段，不自己发明口径。
回执里还有一类记录要人工看：设备内置的物联网卡、境外运营商号码、转售企业系号段，这三种取不到状态，但批次不会因此失败。把它们和失败条目混在一起统计，成功率会莫名其妙掉一截，排查方向也会被带偏。批量查询里这三类号码怎么单独处理，手机号在网状态批量查询：一次多少、量怎么算里给过一份口径。
看三个问题：提交之后能不能拿到批次号与完成窗口？进度不动时，回执里有没有可查的分片与错误码？批次收尾的三类数字是否分开统计？
三个问题里有两个是否定的，先别急着扩批次大小。批量任务的毛病不会在接口那一侧解决，它属于集成层的接口约定：回执做全了，值班同学能回答「还要多久」；回执没做全，再快的接口也只换来一个不知道含义的百分比。这条链路如果打算直接对接现成服务，可以从【手机号在网状态 API】起步：直连三网，返回八种状态，支持携号转网识别，鉴权走请求头携带 AppCode，按次计费、即买即用，字段定义与计量口径以商品详情页文档为准。
文章评论
发表评论
请先注册/登录后评论