首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >「域名健康度体检」接口功能详解|数据鱼API

「域名健康度体检」接口功能详解|数据鱼API

原创
作者头像
用户12862874
发布于 2026-11-21 21:25:42
发布于 2026-11-21 21:25:42
60
举报

接口简介

「域名健康度体检」是数据鱼API平台面向邮件送达能力的评分接口,Base 路径 /api/domain-health,共 3 个端点。它围绕一个域名的三项邮件基础设施配置做布尔判定:是否存在 SPF 所依赖的 TXT 记录、DMARC 专用子域上是否有 TXT 记录、主域是否配置 MX,并用固定权重合成 0–100 的分数,同时给出检查时间。

这个接口输出的是结论而不是明细:不返回每条 TXT 的原文,也不返回 MX 主机与优先级,只回答「配没配」和「总分多少」。因此它适合放在资产台账与巡检报表里,作为一列状态字段;需要查看具体记录内容时,应改用按记录类型返回明细的解析查询能力。

评分口径固定:SPF 项 33 分、DMARC 项 33 分、MX 项 34 分,满分 100。三项都为真时得 100,全缺失时为 0,不存在部分扣分或人工加权。检查通过系统 DNS 解析完成,不访问网页、不探测端口,也不涉及证书与域名注册信息——这些不属于本接口的检查范围。

端点总览

方法

路径

说明

鉴权

GET

/api/domain-health/ping

健康检查,返回服务版本与时间

免鉴权

GET

/api/domain-health/check

查询参数方式执行体检

需要

POST

/api/domain-health/check

请求体方式执行体检,参数同名

需要

通用约定

鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013。响应为 {code, msg, data} 三段结构,code 为 0 表示成功;ping 的成功消息是 pong,check 的是 success。参数类错误包括 4001 缺少必填参数、4002 格式非法、4003 取值不在支持列表、4004 查询目标未收录;4040 为路由不存在,4050 为方法不允许,5000/5001 为服务内部错误,5031/5032 表示上游依赖不可用且不会以占位数据冒充结果。同一路径的 GET 与 POST 共用一套参数名,POST 支持 JSON body 或表单。这是数据鱼API平台开发工具类接口的共同约定。

核心端点详解

域名体检(GET/POST /check)

用途:对单个域名执行三项配置判定并返回评分。

参数

类型

必填

默认

说明

domain

string

是

—

待体检的域名,原样回显

API.md 把 domain 标为可选,但实现中为空即返回 4001 Missing domain,两种调用方式都必须携带。接口不做格式预校验:传入不符合域名规范的字符串不会得到 4002,而是三项判定全部为假、得分 0——「域名无效」与「配置全缺」在响应上不可区分,调用方需在本地先校验格式。

返回字段要点:domain 为请求原值;spf_configured、dmarc_configured、mx_configured 为三个布尔判定;score 为整数评分,按 33/33/34 加权;last_checked 为服务端检查时间,格式 Y-m-d H:i:s,无时区标记。响应中不含单项扣分原因,也不含原始记录。

代码语言:javascript
复制
GET /api/domain-health/check?api_key=YOUR_KEY&domain=YOUR_DOMAIN
代码语言:javascript
复制
POST /api/domain-health/check?api_key=YOUR_KEY
Content-Type: application/json

{"domain":"YOUR_DOMAIN"}

两种方式返回结构完全一致,可任选其一;批量场景由调用方循环调用,接口本身不接受域名数组。

健康检查(GET /ping)

用途:探活与版本核对。无参数、免鉴权,返回 data.version(当前 1.0.0)与 data.time。适合作为监控探针,或在上线前确认实例版本。

代码语言:javascript
复制
GET /api/domain-health/ping

数据与限制

  • 检查项固定 3 项:TXT(SPF 项)、DMARC 子域 TXT、MX,不支持自定义检查项。
  • 评分权重固定为 33、33、34,合计 100;每一项只有已配置与未配置两种状态,无中间档。
  • 单次只处理一个域名,无批量参数、无并发编排。
  • 检查结果不缓存、不落库,last_checked 由服务端在响应时生成。
  • 每项判定依赖系统 DNS 解析,受本地解析器缓存与上游 TTL 影响;解析超时会被当作未配置处理。
  • 不检查域名是否已注册、是否过期、是否启用 DNSSEC,也不检查 TLS 证书。

典型使用场景

  • 邮件可达性台账:对发信域名逐个体检,把 score 与三个布尔值写入表格,按季度对比配置变化。
  • 新域名上线检查:配置发信前先跑一次,三项全为真再放行,避免上线后才发现 DMARC 缺失。
  • 告警规则输入:把 score 低于阈值或某一项由真变假作为触发条件,纳入既有监控。
  • 供应商准入:接收外部发信域名清单,批量体检后作为准入材料的一部分。

注意事项

  • 文档与实现有两处不一致:domain 标注为可选,实际必填并返回 4001;ping 示例携带了 Key,但端点声明为免鉴权。以实测行为为准。
  • spf_configured 的判定只看该域是否存在任意 TXT 记录,不解析记录内容是否以 v=spf1 开头。存在一条无关的 TXT(例如站点验证串)就会判为真,因此该字段不能等同于「SPF 策略有效」。
  • DMARC 项只检查专用子域上是否存在 TXT,不解析 p= 策略,也不判断记录是否语法正确;p=none 与 p=reject 得到相同结果。
  • 无效域名不会返回 4002/4003,而是三项全假、得分 0;若把 0 分直接解读为「配置缺失」,会把格式错误误判为运维问题。
  • 评分是线性加权而非风险分级,33 分的差距不代表同等风险;需要判断优先级时应看具体哪一项为假。
  • last_checked 无时区标识,跨时区汇总时需约定按服务端时区解释。
  • 数据时效:结论反映查询瞬间的 DNS 视图,记录变更后可能因缓存延迟才体现;数据鱼API只做判定与计分,不修改任何解析配置。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 域名体检(GET/POST /check)
    • 健康检查(GET /ping)
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档