为何需要 DNS 查询 API在开发网络监控、安全扫描或域名检测工具时程序化获取 DNS 记录是常见需求。自建解析器涉及协议细节RFC 1035而命令行工具不适合批量自动化。一个轻量的 DNS 查询 API 允许开发者以最少的代码完成 A/AAAA/MX/TXT/CNAME 等记录查询且内置 UDP 与 DNS over HTTPS 自动降级机制减少开发负担。本接口由服务端自实现 DNS 协议无需额外依赖库。QPS 上限为 5/s以文档为准适合低频自动化任务。接口能力边界支持的记录类型A、AAAA、MX、TXT、CNAME、NS、SOA、SRV、PTR、CAA。传输协议默认 UDP超时或异常时自动 fallback 到 DoHDNS over HTTPS避免劫持。可指定 DNS 服务器支持逗号分隔多个地址。单请求超时范围130 秒。鉴权方式HTTP Header 中携带Authorization或X-API-Key以实际文档为准。鉴权与请求头每个请求需在 Header 中传递 API Key。示例中使用X-API-Key: $APIZERO_API_KEY实际接入时请替换为真实 Key 并根据最新文档选择正确的 Header 名称。最小可运行示例查询 A 记录curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {domain: example.com, type: A} \ https://v1.apizero.cn/api/dns-lookup若命令执行成功你将收到包含 IP 地址93.184.216.34的 JSON 响应。这是验证 API 连通性的最快方式。参数详解请求体为 JSON 对象各字段说明如下表字段必填类型说明示例值domain是string要查询的域名别名 name/hostexample.comtype否string记录类型可逗号分隔多个ALL表示 A/AAAA/MX/TXT/CNAMEA、A,AAAA,MXserver否stringDNS 服务器地址逗号分隔多个8.8.8.8,1.1.1.1timeout否number单次请求超时秒数1~30默认 55doh否number是否强制走 DoH0自动降级、1强制 HTTPS0doh_provider否stringDoH 服务商cloudflare、google、alibabacloudflare查询多个记录类型以下示例同时查询 A、AAAA、MX 记录curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {domain: example.com, type: A,AAAA,MX, server: 8.8.8.8, timeout: 5} \ https://v1.apizero.cn/api/dns-lookup若type设为ALLAPI 将返回五种常用记录。响应结构解读成功返回 HTTP 200Content-Type 为application/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, truncated: false, elapsed_ms: 32, answers: [ { name: example.com, type: A, value: 93.184.216.34, ttl: 300 } ] } }字段说明code业务状态码0 表示成功。msg描述信息。request_id请求唯一标识可用于日志追踪。data.domain查询的域名。data.type查询的记录类型。data.server实际使用的 DNS 服务器。data.transport传输协议udp或https。data.rcodeDNS 响应码0 为 NOERROR。data.rcode_text响应码文本描述。data.truncated是否被截断UDP 响应超 512 字节时。data.elapsed_ms解析耗时毫秒。data.answers记录列表每项包含name、type、value、ttl。常见错误场景与排查问题可能原因处理方式HTTP 401API Key 缺失或无效检查 Header 中的 Key 是否配置正确HTTP 400参数格式错误如 domain 为空验证请求体 JSON 合法性code非 0DNS 解析失败如域名不存在查看data.rcode和msg判断具体错误响应超时网络问题或指定服务器不可达检查 server 地址、增大 timeouttruncated: trueUDP 响应过大被截断API 会自动使用 DoH 重试可观察 transport 字段工程化注意事项限流设计QPS 上限为 5/s建议在客户端实现令牌桶或延迟队列避免触发限流返回 429具体状态码以文档为准。超时策略除了 API 的timeout参数HTTP 客户端也应设置连接超时如 curl 的--connect-timeout和总超时--max-time防止挂起。缓存机制对于 TTL 较长的记录如 300 秒可在应用层缓存answers减少重复调用。错误重试当 HTTP 5xx 或网络异常时建议采用指数退避重试避免雪崩。日志记录保存每次请求的request_id和elapsed_ms便于排查延迟问题。参考文档API 文档https://apizero.cn/aidocs/dns-lookup原始文档https://apizero.cn/aidocs/dns-lookup/raw.md注意接口参数与行为以实际返回为准本文仅基于提供的事实卡整理。