适用场景DNS 查询是网络基础设施中最基础的依赖之一。当你在以下场景中需要程序化获取域名解析结果时自建的 DNS 查询能力可以避免依赖系统 getaddrinfo 或外部命令如 nslookup的不确定性容器 / 无状态服务中需要独立 DNS 探测例如健康检查、服务发现时的域名可达性验证。多环境域名切换检测灰度发布时对比不同 DNS 服务器返回的解析结果。安全分析 / 威胁情报查询可疑域名的 A 记录、TXT 记录SPF、DKIM或 CNAME 指向。DNS 劫持检测将查询结果与本地公共 DNS 结果比对判断是否存在中间人篡改。本接口实现了完整的 DNS 协议RFC 1035支持九种常见记录类型并内置 UDP 到 DoH (DNS over HTTPS) 的自动降级适用于需要稳定、可编程 DNS 查询的场景。接口能力边界在使用任何 API 之前明确其调用限制是工程化的第一步。以下是 DNS 查询 API 的硬性边界QPS 限制维度值每秒钟最大请求数5 QPS建议实际使用≤ 3 QPS预留重试余量超限后服务端会返回 HTTP 429Too Many Requests响应 body 中包含错误描述。因此在并发请求较大的业务中务必加入本地令牌桶或滑动窗口限流。支持的 DNS 记录类型接口通过type字段指定支持以下记录可逗号分隔组合A– IPv4 地址AAAA– IPv6 地址MX– 邮件交换记录TXT– 文本记录常用于验证、SPFCNAME– 别名NS– 权威名称服务器SOA– 起始授权机构SRV– 服务定位记录PTR– 反向解析CAA– 证书颁发机构授权ALL– 同时查询 A, AAAA, MX, TXT, CNAME便捷快捷传输协议与 fallback默认使用 UDP 查询指定 DNS 服务器。若 UDP 遭遇超时、截断或服务器无响应API 会自动切换到 DoHDNS over HTTPS重试使用doh_provider指定的上游Cloudflare / Google / Alibaba。这种 fallback 设计能显著提高解析成功率尤其是在网络环境复杂如防火墙屏蔽 DNS 端口的情况下。超时限制每个请求的超时范围是 130 秒字段timeout单位秒实际推荐值视网络延迟而定。例如同区域公网 DNS 查询建议 35 秒跨区域或特殊情况可适当放宽。请求参数与鉴权鉴权方式所有请求必须在 HTTP Header 中携带 API KeyAuthorization: Bearer 你的 API Key注意API Key 是字符串需提前从控制台获取。不要与服务端会话 ID 混淆。请求体JSON接口采用 POST 方法Content-Type 固定为application/json。以下是全部参数的字段说明字段名必填类型默认值说明domain是string无要查询的域名别名name/hosttype否stringA记录类型多个用逗号分隔如A,AAAA,MXserver否string系统自动选择DNS 服务器 IP多个用逗号分隔如8.8.8.8,1.1.1.1timeout否number5单请求超时单位秒有效范围 1–30doh否number0是否强制使用 DoH0为自动UDP→DoH1为强制 HTTPSdoh_provider否stringcloudflare强制 DoH 时选择上游供应商cloudflare,google,alibaba提示若server留空系统会依据出口 IP 自动选择延迟较低的公网 DNS。建议生产环境中显式指定一组可靠的 DNS 服务器如 114.114.114.114 和 8.8.8.8。curl 请求示例以下示例查询example.com的 A 和 MX 记录指定 DNS 服务器为 8.8.8.8 和 1.1.1.1超时 5 秒关闭强制 DoH使用自动 fallbackcurl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, type: A,MX, server: 8.8.8.8,1.1.1.1, timeout: 5, doh: 0, doh_provider: cloudflare } \ https://v1.apizero.cn/api/dns-lookup记得将YOUR_API_KEY替换为你的真实密钥。-sS参数使 curl 静默出错但不屏蔽错误信息适合脚本调用。若只想快速测试 A 记录且使用默认服务器可简化为curl -sS -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {domain: example.com} \ https://v1.apizero.cn/api/dns-lookup返回字段解读成功时 HTTP 状态码为 200响应体为 JSON 格式{ code: 0, msg: 成功, request_id: req_abc123, data: { domain: example.com, type: A, server: 114.114.114.114, transport: udp, rcode: 0, rcode_text: NOERROR, elapsed_ms: 32, truncated: false, answers: [ { name: example.com, type: A, value: 93.184.216.34, ttl: 300 } ] } }顶层字段字段类型说明codeint业务状态码0表示成功msgstring状态码对应的描述文字request_idstring本次请求的唯一标识可用于排查日志dataobject查询结果主体data 对象字段类型说明domainstring请求的域名typestring实际查询的记录类型若请求多类型此处为第一个serverstring最终使用的 DNS 服务器 IPtransportstring传输协议udp或dohrcodeintDNS 响应码RFC 10350 为 NOERRORrcode_textstring响应码英文描述如NOERROR,NXDOMAINelapsed_msint查询耗时毫秒truncatedbool响应是否被截断当 UDP 数据包超过 512 字节时可能为 trueAPI 自动 fallback 到 DoHanswersarray[]DNS 应答记录列表answers 数组中的元素字段类型说明namestring资源记录对应的域名typestring记录类型如 A, MXvaluestring记录值A 为 IPMX 为优先级邮件服务器TXT 为文本ttlint生存时间秒当查询多条记录如type: A,MX时answers数组会混合同一域名的多种类型需按type字段区分处理。例如answers: [ {name: example.com, type: A, value: 93.184.216.34, ttl: 300}, {name: example.com, type: MX, value: 10 mail.example.com., ttl: 300}, {name: example.com, type: TXT, value: vspf1 include:_spf.google.com ~all, ttl: 300} ]常见错误与排查HTTP 4xx 错误401 UnauthorizedAuthorizationHeader 缺失或无效。请确认 API Key 正确且未过期。429 Too Many RequestsQPS 超出限制5 QPS。此时响应体包含msg: 请求过于频繁。解决方案引入本地限流或在短时间内减少并发。400 Bad Request请求体 JSON 格式错误或缺少必填字段domain。检查 JSON 是否合法、domain是否为空。业务错误码code 非 0code说明处理建议1001域名格式错误检查域名是否含非法字符或缺失 TLD1002不支持的记录类型检查type值仅支持文档列出的类型1003DNS 服务器不可达检查server列表中的 IP 是否正确或尝试留空让系统自动选择1004查询超时可增大timeout最大 30或减少 DNS 服务器列表以提高并发可访问性1005DoH 上游失败若强制 DoHdoh: 1请确认doh_provider是否有效或切换为cloudflare提示建议在代码中先判断code字段不要仅依赖 HTTP 状态码。部分业务错误仍会返回 200 但code非 0。工程化注意事项1. 限流与重试策略使用令牌桶如 Guava RateLimiter限制每秒请求不超过 4 次留余量给重试。对于 429 错误采用指数退避重试如 1s、2s、4s最大重试 3 次。对于网络超时curl 层面的 Connection Timeout或 503 服务不可用同样需要重试但注意区分服务端限流与临时故障。2. 多记录查询的解析当同时查询多种记录类型时answers数组是扁平化的。建议在客户端按type分组from collections import defaultdict answers response[data][answers] by_type defaultdict(list) for ans in answers: by_type[ans[type]].append(ans) # 现在 by_type[A] 是所有 A 记录3. DoH fallback 的监控transport字段会告诉你实际使用的协议。如果发现大量请求使用 DoH说明 UDP 查询频繁失败此时应检查本地网络是否限制了 DNS 端口53或 DNS 服务器列表是否合理。可以尝试更换为公共 DoH 上游或将server改为内网 DNS。4. TTL 的缓存利用响应中的ttl是权威 DNS 建议的缓存时长。客户端应遵循 TTL 做本地缓存避免对同一域名频繁发起查询。例如对于 TTL300 的记录缓存 300 秒后再查询。注意ALL查询时 TTL 可能因记录类型不同而不同建议取最小值。5. 超时与截断处理当truncated为true时API 会自动回退到 DoH 重试此时响应中的answers不会缺失。但如果doh: 0且 UDP 被截断后 DoH 也失败则可能返回部分结果或异常。建议在业务中忽略truncated字段直接信任 API 的自动处理。超时时间不宜设得过长若同时查询大量域名比如一次请求 50 个域名建议逐个查询并控制并发而不是单请求内设 30 秒——因为每个独立请求的timeout是单独的。6. 重复请求与 request_id每个请求都返回唯一request_id建议结合业务日志记录该 ID在排查问题时提供给后端支持。对于幂等性要求DNS 查询天然幂等同一域名同一记录类型返回结果一致但参数中的server顺序可能影响elapsed_ms与server字段重复请求的request_id一定不同。参考文档API 文档首页https://apizero.cn/aidocs/dns-lookup原始技术文档含更多示例https://apizero.cn/aidocs/dns-lookup/raw.mdDNS 协议标准RFC 1035