DNS 查询 API 参数精讲：从请求到返回的完整解析

适用场景当你的应用需要绕过系统默认 DNS 解析器直接向指定服务器查询域名记录时一个轻量的 DNS 查询 API 能帮你省去自己实现 RFC 1035 的复杂度。常见场景包括自动化运维中批量检测域名的 A 记录或 MX 记录是否变更安全分析时获取特定域名的 TXT、CNAME 记录多 DNS 服务器对比查询验证解析一致性在无 root 权限的环境中需要 DoHDNS over HTTPS防劫持。接口能力边界该 API 基于自实现的 DNS 协议RFC 1035优先使用 UDP 查询若遇超时或截断则自动 fallback 到 DoH通过 HTTPS 发送 DNS 请求避免传统 53 端口被劫持的问题。支持以下记录类型类型说明AIPv4 地址记录AAAAIPv6 地址记录MX邮件交换记录TXT文本记录CNAME别名记录NS域名服务器记录SOA起始授权机构记录SRV服务定位记录PTR反向地址记录CAA证书认证机构记录可通过逗号分隔同时查询多种类型例如type:A,MX,TXT。用户 QPS 为 5每分钟限制 300 次请求以文档为准。请求参数与鉴权API 地址https://v1.apizero.cn/api/dns-lookup请求方法POSTContent-Typeapplication/jsonHeader 鉴权参数类型必填说明Authorizationstring是API Key格式Bearer your_api_key实际测试中发现接口也兼容X-API-Key头部见 curl 示例但文档以Authorization为准。建议两种方式都支持优先使用Authorization。请求体 (JSON Object)字段类型必填默认值说明domainstring是-查询的域名别名 name/hosttypestring否ALL记录类型逗号分隔。示例A、MX,TXT、ALL等于 A,AAAA,MX,TXT,CNAME…serverstring否114.114.114.114DNS 服务器 IP逗号分隔最多 3 个。示例8.8.8.8,1.1.1.1timeoutnumber否5单请求超时秒数范围 1~30dohnumber否0是否强制走 DoH0自动回退1强制 HTTPS 查询doh_providerstring否cloudflareDoH 服务商cloudflare / google / alibaba。当 doh1 时生效参数type的默认值为ALL但实际 API 内部会展开为全部支持的类型。如果只需要指定类型建议显式传入以提高效率。curl 示例可复制# 替换 YOUR_API_KEY 为你的实际密钥 export API_KEYYOUR_API_KEY curl -sS -X POST \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, type: A, server: 8.8.8.8, timeout: 5, doh: 0 } \ https://v1.apizero.cn/api/dns-lookup返回示例格式化后{ code: 0, msg: 成功, request_id: req_abc123, data: { domain: example.com, type: A, server: 8.8.8.8, transport: udp, rcode: 0, rcode_text: NOERROR, elapsed_ms: 32, truncated: false, answers: [ { name: example.com, type: A, ttl: 300, value: 93.184.216.34 } ] } }Python 代码接入使用requests库实现一次查询import requests API_URL https://v1.apizero.cn/api/dns-lookup API_KEY your_api_key_here # 替换为真实 Key headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { domain: example.com, type: A,MX, server: 8.8.8.8, timeout: 5, doh: 0 } try: resp requests.post(API_URL, headersheaders, jsonpayload, timeout10) resp.raise_for_status() result resp.json() if result[code] 0: print(查询成功耗时, result[data][elapsed_ms], ms) for ans in result[data][answers]: print(f{ans[type]} {ans[name]} - {ans[value]} (TTL{ans[ttl]})) else: print(错误码, result[code], 错误信息, result[msg]) except requests.exceptions.RequestException as e: print(网络请求失败, e)返回值逐字段解读响应是一个 JSON 对象顶层包含code、msg、request_id和data。顶层字段类型说明codeint业务状态码0 表示成功非 0 详见错误表msgstring提示信息成功时“成功”失败时给出具体原因request_idstring本次请求唯一标识便于问题排查dataobject查询数据主体data 详解字段类型说明domainstring查询的域名typestring请求的记录类型多个时逗号分隔serverstring实际使用的 DNS 服务器多个时显示第一个成功响应的transportstring传输协议udp或httpsDoHrcodeintDNS 响应码0NOERROR3NXDOMAIN 等rcode_textstring可读的响应码解释elapsed_msint查询耗时毫秒truncatedbool响应是否被截断通常表示 UDP 结果过大需改用 DoH 或 TCPanswersarray答案列表每个元素包含以下字段answers 数组元素字段字段类型说明namestring记录对应的域名typestring记录类型如 A、MXttlint生存时间秒valuestring记录值IP、域名、或文本对于 MX 记录value 格式通常为10 mail.example.com.其中优先级与目标由空格分隔。常见错误与处理code含义处理建议1001参数缺失如未传 domain检查请求体字段1002域名格式无效domain 不能包含协议前缀或端口1003不支持的记录类型仅支持文档列出的 10 种类型1004DNS 服务器不可达或超时尝试增加 timeout或使用 doh1 走 HTTPS2001认证失败API Key 无效或缺失检查 Header 中的 Authorization2002频率超限QPS 5增加重试间隔或实现本地缓存注意服务端返回 HTTP 状态码通常为 200业务错误通过 code 体现但鉴权失败时会返回 401 或 403。工程化注意事项1. 缓存策略DNS 记录的 TTL 通常为 60~86400 秒。建议在客户端缓存查询结果避免同一域名的重复请求。根据 TTL 设置过期时间过期后重新查询。2. 超时设计业务层请求超时应设置为 (timeout * 重试次数 buffer)。例如 timeout5最多重试 2 次则 HTTP 超时可设为 12 秒。3. 多个 DNS 服务器与容错server 参数支持逗号分隔多个 DNS 服务器如8.8.8.8,1.1.1.1,114.114.114.114。API 内部会按顺序尝试直到某个服务器成功返回。但建议至少指定 2 个权威公共 DNS以提升可用性。4. DoH 强制模式在网络环境较差防火墙丢弃 UDP 53 包时可以设置doh1并配合doh_providercloudflare所有查询通过 HTTPS 加密传输。代价是延迟略有增加。5. 日志与监控记录request_id和elapsed_ms当code ! 0或elapsed_ms 3000时触发告警。注意truncatedtrue时建议下次请求使用 DoH 以获得完整结果。6. 批量查询API 单次只接受一个域名。如果需要批量查询可以并发发送请求注意 QPS 限制 5 次/秒采用协程或线程池控制并发数。7. 响应 rcode 处理rcode0(NOERROR)正常rcode3(NXDOMAIN)域名不存在rcode2(SERVFAIL)服务器错误可重试rcode5(REFUSED)服务器拒绝建议根据rcode_text输出友好提示。参考文档DNS 查询 API 文档原始 Markdown 文档RFC 1035: Domain Names - Implementation and Specification