「DNS 域名解析查询」是数据鱼API平台提供的协议级 DNS 查询接口,Base 路径 /api/dns,共 8 个端点。它按记录类型分组返回完整应答,覆盖 A、AAAA、CNAME、MX、NS、TXT、SOA、PTR、SRV、HINFO、NAPTR、CAA、DNSKEY、DS、TLSA 共 15 种类型。其中 CAA、DNSKEY、DS、TLSA 四种不被 PHP 扩展原生支持,由自建的原生 UDP 报文通道解析,因此这四类记录并非降级占位,而是与其余类型同一条链路产出。
解析链路的主通道是自实现的 UDP DNS 客户端:把一批「域名 × 类型」的问题一次性发出,单轮往返并发收包;nslookup 只作为兜底,仅在没有 socket、取不到系统 DNS 或服务器完全不回包时启用。每轮查询附带一个存活探针,用于区分「服务器不回包」与「服务器回了 NXDOMAIN/NODATA」这两种语义完全不同的结果;整批查询后若某域名一条应答都没收到,再发起一轮 1.0 秒超时的定向重试,正常应答不触发,因此不增加常规耗时。
结果写入双层缓存:进程内 LRU(容量 2000、TTL 上限 300 秒)与 Redis(TTL 取记录最小 TTL,限制 60–86400 秒;无记录负缓存 1 小时)。IDN 中文域名自动转 Punycode,反向解析走 UDP PTR → nslookup 双通道回退。这套结构面向「一次问清一个域名的多种记录」与「一次问清多个域名」两类工作。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/dns/ping | 健康检查,返回版本、记录类型数与批量上限 | 免鉴权 |
GET | /api/dns/types | 列出 15 种记录类型代号与中文描述 | 免鉴权 |
GET | /api/dns/servers | 列出常用公共 DNS 服务器,可直接作为 server 参数 | 免鉴权 |
GET | /api/dns/stats | 返回缓存状态、批量上限、限流配置等运行指标 | 免鉴权 |
GET | /api/dns/self | 用 IANA 保留测试域名对整条链路做自检 | 免鉴权 |
GET | /api/dns/resolve | 解析指定域名的多种记录类型,可按服务器查询 | 需要 |
GET | /api/dns/reverse | 对 IPv4/IPv6 地址做 PTR 反向解析 | 需要 |
POST | /api/dns/batch | 批量解析最多 10 个域名,请求体为 JSON | 需要 |
鉴权用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013;API.md 总述写「所有接口均需鉴权」,但 ping、types、servers、stats、self 五个端点的说明与示例均未带 Key,接入以端点级说明为准。限流按 API Key 或客户端 IP 隔离,令牌桶容量 100、补充速率 10 令牌/秒,批量按清洗后的域名数量扣令牌,自检也会消耗 1 个令牌。
响应统一为 {code, msg, data} 三段结构,code 为 0 表示成功。本接口特有错误码:4001 缺少参数,4002 参数过长或记录类型、DNS 服务器无效,4003 域名或 IP 非法,4006 批量超限,4290 限流(data 带 retry_after),5001 查询失败。这是数据鱼API平台开发工具类接口的通用约定,换接口时可复用同一套错误处理分支。
用途:对一个域名按指定类型集合解析,返回按类型分组的记录。结果写入双层缓存,并附带 5 分钟 HTTP 缓存头与 ETag。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
domain | string | 是 | — | 待解析域名,支持 IDN 中文,最长 253 字符 |
types | string | 否 | 全部 15 种 | 逗号分隔的类型,如 A,MX;支持 ALL/ANY;亦接受 type 别名 |
server | string | 否 | 系统默认 | IP 或别名 google/cloudflare/quad9/opendns/dnspod/alidns/114 |
force | bool | 否 | false | 跳过缓存强制回源,接受 1/true/yes/on |
返回字段要点:domain 为原始输入,ascii_domain 为 Punycode 后的形式,is_idn 标识国际化域名;server 回显实际服务器,system 表示系统默认;types 为排序后的实际查询类型;record_count 为记录总数,min_ttl 为最小 TTL,0 表示无记录;records 以类型代号为键,字段随类型而变——A 给 ip,AAAA 给 ipv6,CNAME、NS、MX 给 target,MX 另有 pri,TXT 给 txt,SOA 给授权字段组,SRV 给 pri/weight/port/target,CAA 给 flags/tag/value;cached、queried_at、elapsed_ms 描述本次查询的缓存与耗时。
GET /api/dns/resolve?api_key=YOUR_KEY&domain=YOUR_DOMAIN&types=A,MX&server=google用途:由 IP 反查主机名,用于日志、访问控制与资产归属核对。主通道为 UDP PTR 查询(一次往返,2 秒超时),失败后由 nslookup 兜底。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
ip | string | 是 | — | IPv4 或 IPv6 地址 |
force | bool | 否 | false | 跳过缓存强制回源 |
返回 ip、version(IPv4/IPv6)、去重后的 ptr 数组、has_ptr 布尔值,以及 cached、queried_at、elapsed_ms;当 has_ptr 为 false 时额外带 note 说明未找到 PTR 记录。没有 PTR 也是有效结果,不应按错误处理。
GET /api/dns/reverse?api_key=YOUR_KEY&ip=8.8.8.8用途:一次解析多个域名,适合巡检与批量核对。请求体为 JSON,域名数组先做严格校验(去空白、长度、格式、类型),任意一条非法即整批返回 400,不跳过也不截断。
参数 | 类型 | 必填 | 默认 | 说明 | |
|---|---|---|---|---|---|
domains | string[] | 是 | — | 域名数组,最多 10 个,每个最长 253 字符 | |
types | string \ | string[] | 否 | 全部 15 种 | 逗号分隔字符串或数组,支持 ALL/ANY |
server | string | 否 | 系统默认 | IP 或别名 | |
force | bool | 否 | false | 跳过缓存 |
响应 data 含 list、total、error_count、errors、truncated、max_limit。list[] 的每项带 query(原始域名)、code、msg,成功时 data 与 resolve 的 data 结构相同;单条查询失败记为 5001 并计入 error_count,不使整批失败。truncated 为保留字段,恒为 false;域名超过 10 个直接返回 4006,并在 data 中给出 max_limit 与 received。
POST /api/dns/batch?api_key=YOUR_KEY
Content-Type: application/json
{"domains":["YOUR_DOMAIN_1","YOUR_DOMAIN_2"],"types":["A","MX"]}nslookup。nslookup 不可用时跳过兜底,两者都不导致接口失败。types 默认是全部 15 种,不指定会显著放大应答体积与耗时;调用方应显式列出所需类型,缓存键也按类型集合区分。min_ttl 为 0 表示没有任何记录,不是「缓存立即过期」;判断是否解析成功应看 record_count 与 records,而非只看 code。force 重新回源。aliases 与 servers 清单,可据此纠正别名拼写;批量中的位置错误以 data.index 给出下标。原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。