号码状态查询收成内部共享服务：契约怎么定
三条业务线各自接了一遍接口，密钥存了三份、映射表两套，同一个号码在两张表里结论不同。这篇讲把号码状态查询收成内部共享服务时，契约要固定哪四样东西、原始状态与派生结论为什么分两层、幂等与重试归到哪一层、版本兼容怎么约定。
🎁 免费试用手机号码状态查询 API
直连三网运营商 · 准确率 ≥99.9% · 支持携号转网识别 · 按次计费即买即用
接手一个跑了半年的项目，第一件事往往是数密钥。订单侧一份，工单侧一份，运营的批量任务里还有一份，三份凭据对应三套调用配置，账单上只有一个总数。更麻烦的是结论对不上：同一个号码在两张表里不一样，因为一套映射把「无短信能力」当成了不可触达，另一套把它当成可以外呼。
把号码状态查询收成内部共享服务，是最直接的解法。方案在评审会上卡住的地方却不是架构图，而是契约：超时算谁的、配额怎么分、错误码由谁翻译。评审问到第四个问题时，做服务的同事答不上来了。这几件事定不下来，收口子只是把混乱挪到了下一层。
字段与取值域排在第一。对外接口的状态取值就那么几个，但内部服务要明确：返回的是原始状态码，还是已经算好的结论。取值域一旦含糊，各业务就会各自猜语义，最后又长出两套映射表。
错误码要分三类而不是一类。调用失败、请求合法但拿不到结论、超出配额被拒，这三件事的处置动作完全不同：第一类退避重试，第二类直接归入无结论，第三类要么排队要么找配额。把它们都归到一个「查询异常」里，排查时就只剩翻日志一条路。
超时与重试要划清责任。服务侧给出一个明确的超时上限，调用侧按这个上限排自己的时间预算；服务内部的重试次数要写进契约，让调用方知道最坏情况下会等多久。约定含糊的局面通常是：调用方以为服务会重试三次，服务方以为超时就返回失败。
配额与归属要写清维度。内部服务最容易变成一个人人都能用、谁也不知道用了多少的公共水龙头。契约里按调用方标识分配额度，让每条调用流水都能归属到具体业务线，分摊与限流才有依据，号码状态查询配额在多业务间怎么分摊里把切额度和设闸门的顺序讲过。
契约里只回答一个问题：返回的是事实还是判断。
事实层是接口给的原始状态，正常在网、空号、通话中、不在网、关机、欠费、无短信能力、长时间关机这些值原样带回，不做加工。判断层是本地映射表算出来的结论与动作。
分两层的好处在于可重算。映射规则改了、某个状态的含义被重新解读了，只要原始值还在，结论可以重跑一遍；两层压成一层，写进去的结论就是唯一记录，规则一动就得回头补数据。字段与取值以商品详情页文档为准，本地不要另起一套叫法。
这两件事都放在服务侧，不要推给调用方。
调用方提交一批号码时带上批次标识，服务侧按批次标识做幂等：同一批次重复提交，已经查过的号码直接返回既有结论，不再产生新的调用量。按次计费的接口下，这一条直接影响账单——多个业务重复提交同一批名单是常见的浪费来源。
重试则分两种情况。网络与限流类失败由服务侧按上限退避重试，超过上限就在返回里标出失败原因；参数与格式类错误一次都不重试，直接返回给调用方修。调用方不再关心重试细节，只按契约里的三类错误码分流，订单系统接入号码状态查询：一次批量任务的重构里也提过把这条判断收进网关的好处。
内部服务的变更比对外接口频繁，所以版本约定更值钱。
只加字段不改语义，属于兼容变更，老调用方不用动。语义要变就发新版本号，新旧并行一段时间，等所有调用方切完再下线旧版。契约文档与本地映射表要同版本发布，避免出现文档是新的、映射表还是旧的这种局面。每个版本都标出废弃时间，写在服务目录里，而不是留在某个人的聊天记录中。
接口上线这种动作建议留一个开关：号码状态查询接口上线：灰度、开关与回滚里那套按业务线放量的做法，换成内部服务同样适用。
契约算不算定完，看一条：换一个没参与过项目的人，只看契约文档，能不能独立写出一个正确的调用方。写不出来，说明某样东西还靠口头传递。
再加一条量化标准：把最近一个月的调用流水按调用方汇总，如果每一行都能归属到具体业务线与批次，配额与账单就不会再吵；如果归属率低于九成，先回去补调用方标识，不要急着做降级与限流。
还有一类请求要单独写进契约：装在设备上的物联卡、境外运营商的号码、转售企业放出的号段，这些不在可查范围内，服务侧应当直接按无结论返回并在返回里标出原因，既不计入服务成功率，也不占用重试预算。
内部服务最终还是要落到一个外部数据源上。起步阶段可以直接接现成的：直连三网，返回八种状态，支持携号转网识别，鉴权走请求头携带 AppCode，按次计费、即买即用，字段与错误码含义以商品详情页文档为准——【手机号在网状态 API】。
文章评论
发表评论
请先注册/登录后评论