出发点先让一条请求跑通做性能诊断类工具时最容易陷入的第一步不是选型而是连一次真实请求都发不出去。网站测速诊断接口的设计思路恰好符合“越简单越好”的原则一个 GET 请求、一个必填参数、一组结构清晰的返回字段。本文围绕最小可运行示例展开逐步把一条 curl 命令拆解为可复用的工程实践。适用场景什么时候需要这个接口网站测速诊断接口适合以下场景发布前巡检上线前确认目标站点从公网访问时 DNS 解析、TCP 连接、SSL 握手均正常且 TTFB 在合理范围内。CDN 切换验证切换 CDN 或回源策略后用接口观察最终命中的 URL、重定向次数和耗时分布快速判断链路是否生效。定时监控脚本利用 QPS 2/s 的额度对少量核心 URL 做低频轮询把总耗时和 HTTP 状态码写入日志。故障复盘用户反馈“打开慢”时通过一次请求拿到 DNS、TCP、SSL、TTFB、总耗时五项数据定位瓶颈出在哪一层。需要说明的是该接口返回的是测量时刻的一次性快照不适合作为长期性能基线的唯一数据源——单次结果受网络波动影响较大建议多次采样后取中位数。接口能力边界接口位于https://v1.apizero.cn/api/site-check方法为 GET一次请求返回六类信息DNS 解析耗时TCP 连接耗时SSL 握手耗时TTFB首字节时间总耗时重定向链、SSL 证书摘要、命中 IP/端口、页面体积等辅助信息限速为 2 QPS即每秒最多两次请求。若用于批量巡检需要在调用侧自行控制频率。参数与鉴权Query 参数参数类型必填说明urlstring是目标 URL自动补https://前缀传参时只需要给裸域名或路径即可接口会自动补充协议头。例如urlbaidu.com和urlhttps://baidu.com效果相同。Header 参数参数类型必填说明Authorizationstring是API Key按文档要求配置实际发送请求时示例中使用的是X-API-Key请求头。具体以接口文档的鉴权说明为准。最小可运行示例一条 curl 命令先写一个最精简的形式只需要替换 URL 占位符和目标地址curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/site-check?urlurl把环境变量APIZERO_API_KEY替换为真实 Key将url替换为待测站点curl -sS \ -X GET \ -H X-API-Key: your-api-key-here \ https://v1.apizero.cn/api/site-check?urlexample.com若当前 shell 已配置APIZERO_API_KEY环境变量直接复用第一条即可。加一点可读性用jq格式化输出方便直接观察字段层级curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/site-check?urlexample.com | jq .输出的 JSON 结构如下{ code: 0, data: { final_url: https://www.example.com/, http_code: 200, redirect_count: 1, timing: { connect_ms: 32.5, dns_ms: 15, ssl_ms: 78.4, total_ms: 156.7, ttfb_ms: 145.2 }, url: https://example.com }, msg: 成功 }返回值逐段拆解顶层字段字段类型含义codenumber业务状态码0表示成功msgstring状态描述dataobject核心数据体data 对象字段类型含义urlstring请求时传入的原始 URLfinal_urlstring经过重定向后的最终 URLhttp_codenumber最终响应的 HTTP 状态码redirect_countnumber重定向次数timingobject耗时明细单位毫秒timing 对象字段类型含义dns_msnumberDNS 解析耗时connect_msnumberTCP 连接建立耗时ssl_msnumberSSL/TLS 握手耗时ttfb_msnumber从发起请求到收到响应首字节的耗时total_msnumber总耗时一个常见误区是认为total_ms等于五个分项之和。实际上ttfb_ms已经包含了 DNS、TCP、SSL 的时间total_ms则进一步包含内容下载时间因此不要对它们直接做加法。正确的关系是ttfb_ms覆盖响应首字节之前的所有阶段total_ms覆盖完整请求周期。常见错误与排查思路401 鉴权失败现象返回 HTTP 401 或业务码提示 Key 无效。排查步骤确认X-API-Key头名称与文档一致。确认 Key 前后没有误加空格或换行。确认环境变量APIZERO_API_KEY已正确导出echo $APIZERO_API_KEY。参数缺失或格式错误现象url参数为空、缺失或包含非法字符。排查步骤检查 URL 是否做了 shell 转义特别是包含、?时需要用引号包裹整个地址。检查自动补全逻辑——如果传入了不完整的域名接口会尝试补https://但明显非法的字符串仍可能被拒绝。目标站点不可达现象http_code为 0 或final_url为空。这种情况下重点看data里是否有错误描述字段或观察timing中卡在哪个阶段——例如dns_ms异常高则疑似 DNS 解析问题connect_ms超时则可能与目标端口或防火墙相关。工程化注意事项1. 频率控制接口 QPS 为 2/s批量检测时务必在代码中加节流。简单做法是每次请求后 sleep 500ms 以上或用令牌桶限制并发。2. URL 编码当目标 URL 包含路径、查询参数时需要先做 URL 编码再拼接到请求中。以下 Python 示例演示了正确处理方式import time import urllib.parse import urllib.request import json API_URL https://v1.apizero.cn/api/site-check API_KEY your-api-key-here TARGET https://example.com/path?reftestlangzh encoded urllib.parse.quote(TARGET, safe) request urllib.request.Request( f{API_URL}?url{encoded}, headers{X-API-Key: API_KEY}, methodGET, ) with urllib.request.urlopen(request) as resp: result json.loads(resp.read().decode(utf-8)) print(result[data][timing]) time.sleep(0.6) # 控制在 QPS 范围内注意safe确保包括冒号和斜杠在内的特殊字符全部被编码避免?和影响服务端参数解析。3. 重定向与 final_url 的利用redirect_count大于 0 时业务方应确认final_url是否与预期一致。例如配置了回源策略的站点检测结果中若出现额外跳转可能意味着配置有误。4. 超时处理网络诊断类接口的耗时取决于目标站点状态极端情况下可能较慢。客户端请求超时建议设置在 30 秒以上避免误判为接口故障。5. 结果落库策略建议按“站点 时间点 耗时明细”三要素存储。查询时按站点分组、按时间倒序方便观察趋势。不要只存总耗时——TTFB 与 SSL 耗时分开记录才能真正定位性能劣化层级。从最小示例到工具脚本把 curl 替换成脚本后整个流程可以收敛为三步准备目标 URL 列表。循环调用接口每次请求间隔 600ms 以上。将code0的返回内容写入 JSON Lines 文件code!0的记录到错误日志。以下是一个贴近生产的最小脚本骨架# site_check_snapshot.py import json import time import urllib.parse import urllib.request API https://v1.apizero.cn/api/site-check KEY your-api-key-here TARGETS [example.com, example.org] def check(url: str) - dict: encoded urllib.parse.quote(url, safe) req urllib.request.Request( f{API}?url{encoded}, headers{X-API-Key: KEY}, methodGET, ) with urllib.request.urlopen(req, timeout30) as resp: return json.loads(resp.read().decode(utf-8)) for target in TARGETS: try: payload check(target) if payload.get(code) 0: with open(snapshot.jsonl, a, encodingutf-8) as f: f.write(json.dumps(payload, ensure_asciiFalse) \n) else: print(f{target} 业务异常: {payload}) except Exception as exc: print(f{target} 请求失败: {exc}) time.sleep(0.6)这个脚本不依赖第三方库Python 3.8 可直接运行。需要调整的只有KEY与TARGETS两处。参考文档网站测速诊断文档页https://apizero.cn/aidocs/site-check原始 Markdown 文档https://apizero.cn/aidocs/site-check/raw.md
