适用场景无论是个人博客、企业服务还是 CDN 加速节点网站的访问速度直接影响用户体验。传统的测速工具通常需要手动操作或依赖图形界面无法方便地集成到自动化脚本或监控系统中。网站测速诊断 API提供了一次接口请求即可获取 DNS 解析、TCP 连接、SSL 握手、首字节时间TTFB、总耗时以及重定向链和 SSL 证书摘要的能力非常适合以下场景自动化监控定时检查目标站点各阶段的响应耗时及时发现性能劣化。批量检测结合脚本对多个 URL 进行并发或顺序测速生成报告。故障排查当用户反馈“网站打不开”时快速从服务器端判断是 DNS 问题、网络问题还是 SSL 握手失败。CI/CD 流水线在部署后验证新节点或新域名的网络连通性和延迟。接口能力边界本 API 的QPS 限制为 2 次/秒即每秒最多发送 2 个请求超出会收到限流错误HTTP 429。单次请求可以覆盖以下六个维度的指标DNS 解析时间从发起请求到 DNS 域名解析完成。TCP 连接时间三次握手耗时。SSL 握手时间TLS 协商阶段耗时如果目标是 HTTPS。TTFB从发起请求到收到第一个响应字节的时间。总耗时整个请求从开始到结束的时间。重定向链与最终 URL自动跟踪 301/302 等重定向记录跳转次数和最终地址。此外还会提取响应头中的Content-Type、Content-Length页面体积以及 SSL 证书的签发者、有效期等摘要信息素材中未返回但文档有提及以官方文档为准。请求参数与鉴权请求方法 地址方法GETURLhttps://v1.apizero.cn/api/site-checkQuery 参数参数必填类型说明url是string目标网站的 URL。如果省略协议则自动补https://。例如传入baidu.com实际请求的 URL 会变为https://baidu.com。Header 参数参数必填类型说明Authorization是string用于身份认证的 API Key。具体获取方式请参考官方文档。素材中 curl 示例使用了-H X-API-Key: $APIZERO_API_KEY但按规范应使用Authorization头实际以文档为准。下面示例中均使用Authorization: Bearer YOUR_API_KEY格式。最小可运行示例curl以下 curl 命令演示了最简单的请求方式。你需要将YOUR_API_KEY替换为真实的密钥并将url参数替换为待测网站地址。curl -sS \ -X GET \ -H Authorization: Bearer YOUR_API_KEY \ https://v1.apizero.cn/api/site-check?urlexample.com请求说明-sS静默模式但保留错误输出。-X GET显式指定 GET 方法curl 默认也是 GET可省略。-H添加鉴权头。URL 参数中urlexample.com会自动补全为https://example.com。执行后你会收到类似下面的 JSON 响应已格式化{ code: 0, msg: 成功, data: { url: http://example.com, final_url: https://example.com/, http_code: 200, redirect_count: 1, timing: { dns_ms: 23.1, connect_ms: 28.4, ssl_ms: 65.2, ttfb_ms: 132.5, total_ms: 140.3 } } }使用 Python 代码接入对于需要在程序中集成测速功能的开发者Python 的requests库是最方便的选择。以下是一个最小可运行的 Python 脚本包含完整的错误处理import requests import sys API_URL https://v1.apizero.cn/api/site-check API_KEY YOUR_API_KEY # 替换为真实密钥 def site_check(url: str) - dict: 调用网站测速诊断 API返回 JSON 数据 headers { Authorization: fBearer {API_KEY} } params { url: url } try: resp requests.get(API_URL, headersheaders, paramsparams, timeout10) resp.raise_for_status() return resp.json() except requests.exceptions.RequestException as e: print(f请求出现异常: {e}, filesys.stderr) sys.exit(1) def main(): if len(sys.argv) 2: print(用法: python site_check.py URL) sys.exit(1) target sys.argv[1] result site_check(target) if result.get(code) ! 0: print(fAPI 返回错误: code{result.get(code)}, msg{result.get(msg)}) return data result[data] timing data[timing] print(f目标 URL: {data[url]}) print(f最终 URL: {data[final_url]}) print(fHTTP 状态码: {data[http_code]}) print(f重定向次数: {data[redirect_count]}) print(--- 耗时明细 (毫秒) ---) print(fDNS: {timing[dns_ms]}) print(fTCP: {timing[connect_ms]}) print(fSSL: {timing[ssl_ms]}) print(fTTFB: {timing[ttfb_ms]}) print(f总耗时: {timing[total_ms]}) if __name__ __main__: main()运行方式python site_check.py baidu.com该脚本会打印出测速结果各阶段的毫秒数。你可以将其集成到定时任务或 CI 脚本中依据耗时阈值进行告警。返回值详细解读从素材给出的示例响应可知最顶层是数组但实际单次请求返回的是对象文档示例中用了数组包裹单个对象实际调用直接返回 JSON 对象。以实际响应为准。各字段含义如下字段类型说明codeint业务状态码。0 表示成功非 0 表示错误。msgstring与 code 对应的描述信息。data.urlstring请求时传入的原始 URL可能未补全协议。data.final_urlstring经过重定向后的最终 URL。data.http_codeint最终请求的 HTTP 状态码如 200、301 等。data.redirect_countint重定向跳转次数。data.timing.dns_msfloatDNS 解析耗时单位毫秒。data.timing.connect_msfloatTCP 连接耗时不含 DNS单位毫秒。data.timing.ssl_msfloatSSL 握手耗时如果未使用 HTTPS 则该值为 0单位毫秒。data.timing.ttfb_msfloat首字节时间TTFB单位毫秒。data.timing.total_msfloat从请求到响应结束的总耗时单位毫秒。注意素材未给出 SSL 摘要和页面体积字段这些可能需要在响应data中额外返回具体请参考官方文档。常见错误处理1. HTTP 401 Unauthorized原因Authorization头缺失或提供的 API Key 无效。解决检查密钥是否正确并确保使用了正确的 Header 名称Authorization而非X-API-Key以文档为准。2. HTTP 400 Bad Request原因缺少必填参数url或url格式无法解析。解决检查 Query 参数并确保 URL 字符串正确编码curl 会自动编码Python 的requests也会编码。3. HTTP 429 Too Many Requests原因QPS 超过 2 次/秒。解决在短时间内的请求之间加入至少 500ms 的间隔或者使用队列控制并发。4. 业务状态码非 0原因API 内部处理出错例如目标网站无法访问、DNS 解析失败、连接超时等。解决打印msg字段获取具体原因并检查目标 URL 是否可达。工程化注意事项API Key 管理不要将密钥硬编码在代码中。建议通过环境变量注入例如os.getenv(SITE_CHECK_API_KEY)或使用 .env 文件。超时设置网络请求可能因目标网站响应慢而卡住Python 中建议设置timeout如 10 秒。curl 可加--connect-timeout 5 --max-time 15。限流处理QPS 2/s 意味着批量测速时需要控制并发数。可以使用time.sleep(0.6)间隔或使用令牌桶算法。重定向跟踪API 已经服务端跟踪了重定向链客户端不需要额外设置allow_redirectsFalse。但需要注意如果目标网站重定向次数超过 API 内部限制可能返回部分结果具体以文档为准。结果存储将测速结果结构化存入数据库如 InfluxDB 或 Prometheus便于长期趋势分析。日志记录记录每次请求的 URL、状态码和耗时方便排查问题。参考文档官方文档页https://apizero.cn/aidocs/site-check原始文档rawhttps://apizero.cn/aidocs/site-check/raw.md本文中的 API 参数、响应字段和 QPS 限制均以上述文档为准若存在差异请以官方最新说明为准。