DNS 记录查询接口接入教程：参数、请求示例与结构化返回解读

排查域名解析问题或做域名资产盘点时经常需要查 A、MX、CAA 等各类 DNS 记录。DNS 记录查询接口支持 8 种标准类型和 ANY 模式并把结果做结构化解析。本文从第一次调用讲起要准备什么、最小请求怎么发、返回值怎么看。一、适用场景解析排查检查域名的 A / AAAA 记录是否按预期配置。邮件配置核对查看 MX 记录的优先级与目标主机。安全策略检查查看 CAA 记录限制哪些 CA 可签发证书。域名资产盘点用 ANY 模式一次拉取域名的全部 DNS 配置。监控告警定时查询关键记录发现变更时告警。二、接口能力边界项目说明请求方法GET参数host、type支持类型A、AAAA、NS、CNAME、MX、TXT、CAA、SOA特殊类型ANY一次返回所有类型兼容写法数字 qtype如 1A、15MX、257CAA数据来源3 家国内 DoH 并发查询后合并去重来源标注每条记录通过sources标注来自哪些 DoH需要理解两点能力边界第一结果是多家 DoH 合并去重后的集合不是权威服务器单点返回第二ANY 能一次拿到全部配置但请求与响应体积更大只查单一类型时没必要用 ANY。三、请求参数与鉴权参数共两个参数说明host待查询的域名type记录类型可用 8 种标准类型或 ANY也可传数字 qtype鉴权方式与请求头字段素材未给出以文档为准。因为这是GET请求参数放在查询字符串中接入前请先在文档里确认是否需要携带 Key 以及域名是否支持子域名。四、最小请求示例下面是一个可复制的 curl 模板查询某域名的 MX 记录curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtypeMX用数字 qtype 查询 CAA 记录效果等价curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtype257用 ANY 一次拉取全部类型curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtypeANY对应的 Python 调用示例import requests def query_dns(host: str, record_type: str, api_key: str | None None) - dict: headers {} if api_key: headers[Authorization] fBearer {api_key} resp requests.get( https://v1.apizero.cn/api/dns-query, params{host: host, type: record_type}, headersheaders, timeout10, ) resp.raise_for_status() return resp.json()调用前先对host做基础校验去掉协议前缀与路径只保留域名本身避免把https://example.com/a这类内容直接传进去。五、返回值解读素材明确的结构化要点如下完整字段名以文档为准MX 记录拆成priority优先级与exchange目标主机不用再自己拆字符串。CAA 记录拆成flags、tag、value三个字段。SOA 记录拆成mname、serial等字段。来源标注每条记录带sources字段说明该记录来自哪些 DoH。一个防御式解析示例字段名请按文档实际返回替换def parse_mx(payload: dict) - list: records payload.get(records) or [] # 数组字段名以文档为准 result [] for item in records: if item.get(type) ! MX: continue priority item.get(priority) exchange item.get(exchange) if exchange is None: continue result.append({ priority: priority, exchange: exchange, sources: item.get(sources, []), }) result.sort(keylambda x: (x[priority] is None, x[priority])) return result排序时把优先级为空的记录放到末尾避免None参与比较报错。sources可以用来判断某条记录是否只在单一 DoH 中出现这对排查“解析结果不一致”很有帮助。六、常见错误与排查现象可能原因排查方向参数错误host为空或type不在支持范围核对类型列表与数字 qtype 映射无记录域名未配置该类型记录换 ANY 模式确认其他类型是否存在结果与本地不一致缓存或不同 DoH 数据差异查看sources结合 TTL 判断超时网络抖动或域名解析慢设置超时做有限次重试鉴权失败需要 Key 但未携带以文档为准补充请求头“无记录”不等于调用失败要按空结果处理不要无限重试。七、工程化注意事项输入清洗统一去掉协议头、路径与末尾点只保留域名。类型映射本地维护1A、15MX、257CAA这类数字映射兼容旧调用。结果缓存DNS 有 TTL按 TTL 做短时缓存避免高频重复查询。来源判断多来源一致的记录可信度更高单一来源的记录在告警中标注出来。监控策略只对关键类型如 A、MX、CAA做定时比对ANY 模式不宜高频调用。字段容错结构化字段可能缺失解析时逐项判空不要假设一定存在。参考文档接口文档