最小可运行示例：用一条 curl 完成网站测速诊断全链路检查

出发点：先让一条请求跑通

做性能诊断类工具时，最容易陷入的第一步不是选型，而是连一次真实请求都发不出去。网站测速诊断接口的设计思路恰好符合“越简单越好”的原则：一个 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 参数

传参时只需要给裸域名或路径即可，接口会自动补充协议头。例如url=baidu.com和url=https://baidu.com效果相同。

Header 参数

实际发送请求时，示例中使用的是X-API-Key请求头。具体以接口文档的鉴权说明为准。

最小可运行示例：一条 curl 命令

先写一个最精简的形式，只需要替换 URL 占位符和目标地址：

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/site-check?url=<url>"

把环境变量APIZERO_API_KEY替换为真实 Key，将<url>替换为待测站点：

curl -sS \ -X GET \ -H "X-API-Key: your-api-key-here" \ "https://v1.apizero.cn/api/site-check?url=example.com"

若当前 shell 已配置APIZERO_API_KEY环境变量，直接复用第一条即可。

加一点可读性

用jq格式化输出，方便直接观察字段层级：

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/site-check?url=example.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": "成功" }

返回值逐段拆解

顶层字段

data 对象

timing 对象

一个常见误区是认为total_ms等于五个分项之和。实际上ttfb_ms已经包含了 DNS、TCP、SSL 的时间，total_ms则进一步包含内容下载时间，因此不要对它们直接做加法。正确的关系是：ttfb_ms覆盖响应首字节之前的所有阶段，total_ms覆盖完整请求周期。

常见错误与排查思路

401 鉴权失败

现象：返回 HTTP 401 或业务码提示 Key 无效。

排查步骤：

1. 确认X-API-Key头名称与文档一致。
2. 确认 Key 前后没有误加空格或换行。
3. 确认环境变量APIZERO_API_KEY已正确导出：echo $APIZERO_API_KEY。

参数缺失或格式错误

现象：url参数为空、缺失或包含非法字符。

排查步骤：

1. 检查 URL 是否做了 shell 转义，特别是包含&、?时需要用引号包裹整个地址。
2. 检查自动补全逻辑——如果传入了不完整的域名，接口会尝试补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?ref=test&lang=zh" encoded = urllib.parse.quote(TARGET, safe="") request = urllib.request.Request( f"{API_URL}?url={encoded}", headers={"X-API-Key": API_KEY}, method="GET", ) 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 替换成脚本后，整个流程可以收敛为三步：

1. 准备目标 URL 列表。
2. 循环调用接口，每次请求间隔 600ms 以上。
3. 将code=0的返回内容写入 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}, method="GET", ) with urllib.request.urlopen(req, timeout=30) 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", encoding="utf-8") as f: f.write(json.dumps(payload, ensure_ascii=False) + "\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