零基础接入DNS记录查询API：参数详解与多类型实战

适用场景日常开发与运维中DNS 记录查询是最基础也最频繁的操作之一。无论你是需要确认域名的新 IP 是否生效、验证邮件服务器 MX 记录是否配置正确还是排查 CDN 切流时的 CNAME 状态都离不开稳定且结构化的 DNS 查询能力。以下场景特别适合使用本接口域名归属核查获取域名所有 DNS 记录对比期望值与实际值。CAA 记录检查确认域名授权了哪些 CA 签发证书防止证书泄露。SOA 记录分析查看权威 DNS 服务器和序列号判断主从同步情况。ANY 批量导出一次请求拿到域名全量配置适合自动化巡检脚本。多 DoH 结果对比内置阿里/腾讯/360 三路并发避免单源缓存篡改。接口能力边界该 API 覆盖了 IANA 定义的 8 种标准 DNS 记录类型A、AAAA、NS、CNAME、MX、TXT、CAA、SOA并提供ANY类型等价于同时对前面 8 种各发一次请求后合并结果。特性说明请求方法GET端点地址https://v1.apizero.cn/api/dns-query单用户 QPS10 次/秒并发来源阿里 DNSAliDNS、腾讯 DNSPod、360 DNS结果合并去重输入清洗自动剥离http(s)://、路径、端口仅保留主机名类型编码支持名称如MX、CAA或数字15、257返回格式JSON每条记录携带来源标记sources特别说明ANY模式并非标准 DNS 协议中的 ANY 查询多数公共 DNS 已废弃而是该接口模拟的“一次返回全部类型”更适合开发者在可控环境中使用。参数与鉴权Query 参数参数是否必填类型说明host是string域名自动过滤协议、路径和端口type否string记录类型默认A可用名称或对应数字如1、15、257host示例传入https://baidu.com/path会被自动清洗为baidu.com。type对应数字A1, NS2, CNAME5, MX15, TXT16, AAAA28, CAA257, SOA6SOA 无标准数字此处为约定值建议用名称。Header 参数参数是否必填类型说明X-API-Key否stringAPI Key不传则使用匿名额度有限制以官方文档为准鉴权方式为 HTTP Header 传递推荐在脚本中通过环境变量管理 Key。curl 请求示例以下命令查询baidu.com的 MX 记录使用环境变量$APIZERO_API_KEY传入 API Keycurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/dns-query?hostbaidu.comtypeMX若使用匿名模式直接移除-H头即可curl -sS \ https://v1.apizero.cn/api/dns-query?hostbaidu.comtypeMX快速尝试 ANY 记录curl -sS https://v1.apizero.cn/api/dns-query?hostbaidu.comtypeANY输出结果将被格式化打印到终端便于查看。推荐配合jq工具进一步处理curl ... | jq .Python 代码接入示例import requests import os host baidu.com record_type MX # 或 15 api_key os.getenv(APIZERO_API_KEY, ) # 空字符串使用匿名 headers {} if api_key: headers[X-API-Key] api_key params {host: host, type: record_type} response requests.get(https://v1.apizero.cn/api/dns-query, paramsparams, headersheaders) data response.json() if data[code] 0: records data[data][records] for rec in records: print(f{rec[type]} {rec[name]} - {rec[data]} (TTL{rec[ttl]})) else: print(请求失败:, data[msg])响应字段解读响应示例来自 API 事实卡{ code: 0, msg: 成功, request_id: mota..., data: { exec_ms: 234, host: baidu.com, input: baidu.com, notes: null, total: 2, type: MX, type_code: 15, sources: [alidns, china360, dnspod], records: [ { type: MX, type_code: 15, name: baidu.com, data: 10 mx.maillb.baidu.com., ttl: 600, parsed: { priority: 10, exchange: mx.maillb.baidu.com. }, sources: [alidns, china360, dnspod] } ] } }顶层字段字段类型说明codeinteger0 表示成功非 0 表示失败msgstring状态描述request_idstring本次请求的唯一标识可用于排查dataobject核心返回数据data 字段字段类型说明exec_msinteger服务端总处理时长毫秒hoststring清洗后的实际查询域名inputstring原始输入未清洗前typestring请求的记录类型名称type_codeinteger请求的记录类型数字编码totalinteger返回总记录数sourcesarray[string]参与本次查询的 DoH 来源列表notesstring/null附加说明如缓存未命中通常为 nullrecordsarray[object]DNS 记录列表records 数组中每个对象的字段字段类型说明typestring记录类型名称type_codeinteger记录类型数字namestring域名通常与 host 一致datastring原始记录值如10 mx.maillb.baidu.com.ttlinteger缓存有效期秒parsedobject结构化解析结果类型不同字段不同sourcesarray[string]该记录出现在哪些 DoH 来源中parsed 对象按类型分解A/AAAA 记录无 parsed直接通过data返回 IP。CNAME 记录无 parseddata 为别名域名。NS 记录无 parseddata 为域名服务器名称。MX 记录{ priority: 10, exchange: mx.example.com. }TXT 记录{ strings: [vspf1 include:_spf.example.com ~all] }CAA 记录{ flags: 0, tag: issue, value: letsencrypt.org }SOA 记录{ mname: ns1.example.com., rname: admin.example.com., serial: 2025032701, refresh: 3600, retry: 600, expire: 86400, minimum: 300 }注意TXT 和 CAA 等记录的 parsed 字段仅在 API 文档示例中出现实际以返回为准。当记录类型无法解析时parsed 可能为null。常见错误与处理错误现象可能原因建议排查返回code ! 0msg 含“参数无效”host为空或格式错误如包含空格确保传入裸域名避免协议前缀返回code ! 0msg 含“类型不支持”type传入的数字或名称不在支持列表检查类型参数仅允许 1/2/5/6/15/16/28/257/ANY返回code ! 0msg 含“QPS 超限”单秒请求数超过 10 次增加客户端限流或使用队列串行化请求响应 403 或 msg 含“Key 无效”X-API-Key错误或已过期检查 Key 是否正确是否在有效期内返回code为 0但total为 0域名本身无该类型记录确认域名是否存在且正确或换用 ANY 再试响应中sources缺失某个 DoH该 DoH 服务商暂时不可用接口会自动降级不影响其他来源结果响应时间长5 秒三路 DoH 并发中某一路超时属于正常现象建议设置客户端超时时间为 10 秒工程化注意事项缓存策略DNS 记录本身有 TTL建议在业务侧缓存data.records的下游结果TTL 以记录中的最小值或 TTL 的 80% 作为本地过期时间减少接口调用次数。重试机制网络波动可能导致某次请求失败。推荐使用指数退避重试如 1s、2s、4s最大 3 次但需注意累计 QPS 限制。并发限制单用户 QPS 10若在分布式环境中有多个实例建议前置一层 Redis 或本地线程锁避免全局超限。参数清洗尽管接口会自动剥离协议但建议在客户端先strip()域名并检查是否合法如不包含空格。ANVAny的取舍ANY类型返回全量记录但 payload 可能较大尤其是大型域名。如果只需特定类型请明确指定type以减少带宽。来源标注利用sources数组可用于做“多数投票”验证如果三个 DoH 均返回相同记录置信度更高若仅一个来源返回可能为主观单点建议酌情忽略。数据隐私接口不要求身份认证时也可使用匿名但匿名额度可能低于有 Key 的额度且缺少 request_id 关联以文档为准。生产环境建议准备并发放固定 Key。参考文档API 文档页原始文档Markdown