适用场景手机号归属地查询常用于用户资料补全、风控辅助判断、运营分群等场景。本文围绕一个具体的 GET 接口展开先给出可直接复制的 curl 请求再把它收成函数或模块重点写清鉴权、超时和响应处理。需要说明的是接口的鉴权字段、请求头名称、错误码全集等信息素材未完全给出本文中相关部分以文档为准不做臆测。接口能力边界方法GET地址https://v1.apizero.cn/api/mobile参数mobile11 位中国大陆手机号能力返回归属省份/城市与运营商支持移动/联通/电信主流号段及虚拟运营商号段170/171/174 等接口有两类正常响应形态这一点对工程封装很关键场景is_found字段表现是否错误查询成功true含 province/carrier 等字段否号段未收录false相关字段为空否手机号格式非法—返回 4000是也就是说is_foundfalse不是异常调用方应直接用if判断而不是抛错。非法号码才会走错误码 4000 的分支。参数与鉴权参数只有mobile但校验规则是明确的^1[3-9]\d{9}$。建议在客户端先做一次正则校验减少无效请求。鉴权部分素材未给出具体字段名与请求头形式请以文档为准。封装时应把鉴权信息做成可配置项不要硬编码在业务代码里也不要提交到代码仓库。可复制的 curl 示例下面是一条最小请求API_KEY和请求头名称请按文档替换curl -G https://v1.apizero.cn/api/mobile \ --data-urlencode mobile13800000000 \ -H Authorization: Bearer API_KEY \ --max-time 5-G 表示以 GET 方式发送并把 --data-urlencode 的内容拼到查询串上--max-time 5 是 curl 层面的整体超时防止请求长时间挂起。鉴权头的具体名称以文档为准示例中仅为占位。收成函数Python 版本下面用 requests 封装一个函数包含正则预校验、超时和双形态响应处理import re import requests MOBILE_RE re.compile(r^1[3-9]\d{9}$) BASE_URL https://v1.apizero.cn/api/mobile class MobileLookupError(Exception): def __init__(self, code, message): super().__init__(f[{code}] {message}) self.code code self.message message def query_mobile(mobile: str, api_key: str, timeout: float 5.0) - dict: if not MOBILE_RE.match(mobile):raise ValueError(手机号格式非法需满足 ^1[3-9]\\d{9}$) resp requests.get( BASE_URL, params{mobile: mobile}, headers{Authorization: fBearer {api_key}}, timeout(3.05, timeout), ) resp.raise_for_status() data resp.json() code data.get(code) if code not in (0, None) and code ! 200: raise MobileLookupError(code, data.get(message, unknown)) if not data.get(is_found): return {found: False, mobile: mobile} return { found: True, mobile: mobile, province: data.get(province), city: data.get(city), carrier: data.get(carrier), }几点说明timeout(3.05, timeout) 分别设置连接超时与读取超时避免连接阶段和读取阶段共用同一阈值。业务成功码的具体取值以文档为准示例中的判断逻辑按实际返回字段调整。返回结构做了收敛把 is_foundfalse 统一转成 found: False上层不必关心原始字段细节。返回值解读成功响应中is_foundtrue 时读取 province、city、carrieris_foundfalse 时这些字段为空。封装层应把「未收录」和「查询失败」分开表达前者是可预期的业务结果后者才需要告警或重试。常见错误4000手机号格式非法。通常是客户端漏校验或传入了带空格、带国家码的号码建议在入口统一清洗。鉴权失败类错误请求头缺失或 Key 无效以文档给出的错误码为准。超时与网络异常属于传输层问题应在封装层捕获并做有限重试。工程化注意事项鉴权信息走环境变量或配置中心不写进源码。缓存策略可参考接口说明成功结果 7 天未查询到 1 小时。号段分配相对静态本地缓存能明显减少重复请求未收录结果缓存时间要短避免新放号段被长期误判。日志脱敏接口侧对错误日志中的手机号做了自动脱敏如 138****0000应用侧日志同样应遵循该规范。并发控制批量查询时加信号量或队列避免瞬时打满连接池。重试只针对超时和 5xx不要对 4000 这类参数错误重试。参考文档手机号归属地接口文档https://apizero.cn/aidocs/mobiletext