httpstat

httpstat 以优雅清晰的方式可视化 curl(1) 的统计信息。

它是一个单文件🌟 Python 脚本，零依赖👏，兼容 Python 3🍻。

特性

• 漂亮的终端输出 — 展示 DNS、TCP、TLS、服务器处理及内容传输的时间分解
• 结构化 JSON 输出 — 通过 --format json / jsonl 提供机器可读的输出，采用稳定的 v1 架构
• SLO 阈值检查 — 使用 --slo total=500,connect=100，违反时退出码为 4
• 保存结果到文件 — --save path.json 用于多步骤工作流
• NO_COLOR 支持 — 遵从 NO_COLOR 约定
• 代理技能 — 内置 技能，支持代理辅助的 HTTP 性能诊断

安装

有三种方式获取 httpstat：

• 直接下载脚本：wget https://raw.githubusercontent.com/reorx/httpstat/master/httpstat.py

• 通过 pip：pip install httpstat

• 通过 Homebrew（仅 macOS）：brew install httpstat

Windows 用户建议使用 @davecheney 的 Go 版本。 → 下载链接

技能

httpstat 附带一个代理 技能，该技能教会 AI 编程助手（Claude Code、Cursor 等）如何使用 httpstat 进行 HTTP 性能诊断——自动安装、瓶颈识别以及可操作性的修复建议。

将技能安装到你的项目中：

npx skills add reorx/httpstat

安装后，当你提出诸如“这个 API 为什么慢？”或“调试这个端点的延迟”之类的问题时，你的代理将自动使用 httpstat。

用法

简单使用：

python httpstat.py httpbin.org/get

如果通过 pip 或 brew 安装，可以直接使用 httpstat 命令：

httpstat httpbin.org/get

cURL 选项

由于 httpstat 是 cURL 的封装，你可以在 URL 之后传递任何 cURL 支持的选项（除了 -w、-D、-o、-s、-S，这些已被 httpstat 使用）：

httpstat httpbin.org/post -X POST --data-urlencode "a=b" -v

结构化输出

使用 --format（-f）获取机器可读输出：

httpstat httpbin.org/get --format json

{
  "schema_version": 1,
  "url": "httpbin.org/get",
  "ok": true,
  "exit_code": 0,
  "response": {
    "status_line": "HTTP/2 200",
    "status_code": 200,
    "remote_ip": "...",
    "remote_port": "443",
    "headers": {"Content-Type": "application/json", "Server": "nginx", "...": "..."}
  },
  "timings_ms": {
    "dns": 5, "connect": 10, "tls": 15,
    "server": 50, "transfer": 20, "total": 100,
    "namelookup": 5, "initial_connect": 15,
    "pretransfer": 30, "starttransfer": 80
  },
  "speed": { "download_kbs": 1234.5, "upload_kbs": 0.0 },
  "slo": null
}

使用 --format jsonl 可获取紧凑的单行 JSON（适用于日志管道）。

SLO 阈值

检查响应时间是否超过阈值。违反时退出码为 4：

httpstat httpbin.org/get --slo total=500,connect=100,ttfb=200

支持的键：total、connect、ttfb（首字节时间）、dns、tls。

在美观模式下，违反信息会在输出末尾以红色打印。 在 JSON 模式下，违反信息出现在 slo 字段中：

{
  "slo": {
    "pass": false,
    "violations": [
      { "key": "total", "threshold_ms": 500, "actual_ms": 823 }
    ]
  }
}

保存结果

将结构化的 JSON 输出写入文件（适用于任何 --format）：

httpstat httpbin.org/get --save result.json
httpstat httpbin.org/get --format json --save result.json

环境变量

httpstat 提供了一系列环境变量来控制其行为。 以下是一些使用示例，你也可以运行 httpstat --help 查看完整说明。

• HTTPSTAT_SHOW_BODY

  设置为 true 可在输出中显示响应正文，注意正文长度限制为 1023 字节，超出将被截断。默认值为 false。

• HTTPSTAT_SHOW_IP

  默认情况下 httpstat 会显示远程和本地的 IP/端口地址。 设置为 false 可禁用此功能。默认值为 true。

• HTTPSTAT_SHOW_SPEED

  设置为 true 可显示下载和上传速度。默认值为 false。

  root@kitploit:~

  HTTPSTAT_SHOW_SPEED=true httpstat http://cachefly.cachefly.net/10mb.test
  
  ...
  speed_download: 3193.3 KiB/s, speed_upload: 0.0 KiB/s
  

• HTTPSTAT_SAVE_BODY

  默认情况下 httpstat 将正文存储在临时文件中， 设置为 false 可禁用此功能。默认值为 。

为了方便，你可以在 .zshrc 或 .bashrc 中导出这些环境变量， 例如：

export HTTPSTAT_SHOW_IP=false
export HTTPSTAT_SHOW_SPEED=true
export HTTPSTAT_SAVE_BODY=false

相关项目

以下是各种语言的实现：

• Go：davecheney/httpstat

  这是 httpstat 的 Go 替代版本，使用纯 Go 编写，不依赖外部程序。如果你喜欢稳定的二进制执行文件，可以选择它（实际上我就是这么做的）。

• Go（库）：tcnksm/go-httpstat

  该项目除了作为 CLI 工具外，还可用作库来帮助调试 Go 代码中 HTTP 请求的延迟，非常贴心且实用，更多信息请参见这篇文章

• Bash：b4b4r07/httpstat

  这正是一开始我想做的事情，但因为对 Bash 技能不够自信而放弃了，干得好！

• Node：yosuke-furukawa/httpstat

  b4b4r07 在他的文章中提到了这个项目，也可以作为 HTTP 客户端使用。

• PHP：talhasch/php-httpstat

  @talhasch 的 PHP 实现

httpstat 中的部分代码块复制自我的其他项目，欢迎查看：

• reorx/python-terminal-color 即插即用的单文件库，用于打印终端颜色。

• reorx/getenv 带类型的环境变量定义。