httptap 是一个 Python CLI 工具，可将 HTTP 请求拆解为具体阶段（如 DNS 解析、TCP 连接、TLS 握手和数据传输），以生成详细的水瀑布时间线。https://t.co/kAObEsHHuD https://t.co/nzyzNHWvCI

ozeranskii/httptap 来源：https://github.com/ozeranskii/httptap

httptap 发布 CI 质量 安全 项目信息

httptap 是一个功能丰富的 CLI 工具，可将 HTTP 请求剖析为每个有意义的阶段——DNS、TCP 连接、TLS 握手、服务器等待和主体传输——并以时间线表格、紧凑摘要或机器可读指标的形式呈现结果。它专为交互式故障排查、回归分析和性能基线记录而设计。

目录

• 亮点
• 对比
• 环境要求
• 安装
• 使用 Homebrew (macOS/Linux)
• 使用 uv
• 使用 pip
• 从源码安装
• Shell 补全
• 快速开始
• 基本 GET 请求
• 带数据的 POST 请求
• 其他 HTTP 方法
• 自定义请求头
• 重定向与 JSON 导出
• 输出模式
• 高级用法
• SLO 阈值检查
• 环境变量
• 退出码
• 发布
• 示例输出
• JSON 导出结构
• 纯指标脚本
• 高级用法
• 开发
• 贡献
• 许可证
• 致谢

亮点

• 分阶段计时 – 基于 httpcore 的 trace 钩子构建的精确测量值（在缺少底层数据时有合理的回退机制）。
• 所有 HTTP 方法 – GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS，并支持请求体。
• 请求体支持 – 可内联或从文件发送 JSON、XML 或任意数据，自动检测 Content-Type。
• IPv4/IPv6 感知 – 解析器和 TLS 检查器会同时报告地址及其地址族。
• TLS 洞察 – 自动捕获证书 CN、到期倒计时、密码套件和协议版本。
• 多种输出模式 – 富水瀑布视图、紧凑单行摘要，或用于脚本的 --metrics-only。
• JSON 导出 – 持久化完整的步骤数据（包括重定向链），便于后续处理。
• SLO 阈值检查 – --slo total=500,ttfb=200 可基于各阶段延迟预算来把关 CI 任务、定时探针和就绪检查；违反时返回非零退出码，同时仍渲染完整报告。
• 可扩展 – 为 DNS、TLS、计时、可视化和导出提供干净的 Protocol 接口，以便接入自定义行为。

📣 httptap 用户专享：在 GitKraken Pro 上节省 50%。捆绑 GitKraken Client、VS Code 版 GitLens 和强大的 CLI 工具，加速每个仓库工作流。

对比

何时选择什么工具：

• httptap — 交互式故障排查、回归分析，以及基于结构化 JSON 的脚本化基线。
• curl -w — 一次性 shell 检查，且 curl 本就需要安装。
• httpstat — 在已有 curl 安装基础之上的快速可视化分解。
• httpie — 通用请求/响应探索，而非延迟剖析。

环境要求

• Python 3.10-3.15 (CPython)
• macOS、Linux 或 Windows（已在 CPython 上测试）
• 除标准网络外，无系统依赖
• 代码必须遵循 Google Python 风格指南（文档字符串、格式）。参见 Google Python 风格指南 (https://google.github.io/styleguide/pyguide.html)

安装

使用 Homebrew (macOS/Linux)

shell brew install httptap

使用 uv

shell uv pip install httptap

使用 pip

shell pip install httptap

容器镜像

shell docker run --rm ghcr.io/ozeranskii/httptap:latest https://example.com

多架构（linux/amd64、linux/arm64），使用 cosign（无密钥 Sigstore）签名，并附带 SLSA 构建来源。

从源码安装

shell git clone https://github.com/ozeranskii/httptap.git cd httptap uv venv uv pip install .

Shell 补全

Homebrew 安装

如果你通过 Homebrew 安装了 httptap，安装后 shell 补全会自动可用。只需重启 shell：

``shell

重启您的 shell 或重新加载配置

exec $SHELL ``

Homebrew 会自动将补全安装到：

• Bash：$(brew --prefix)/etc/bash_completion.d/
• Zsh：$(brew --prefix)/share/zsh/site-functions/

Python 包安装

如果你通过 pip 或 uv 安装了 httptap，需要安装可选的补全扩展：

1. 安装补全扩展： ``shell uv pip install “httptap[completion]”

或

pip install “httptap[completion]” ``

2. 激活你的虚拟环境： shell source .venv/bin/activate

3. 运行全局激活脚本以启用参数补全： shell activate-global-python-argcomplete

4. 重启你的 shell。补全现在应该可以在 bash 和 zsh 中正常工作。

注意： 全局激活脚本仅提供 bash 和 zsh 的参数补全。其他 shell 不在该脚本的覆盖范围内，必须单独配置。

使用示例

补全安装完成后，可以使用 Tab 键自动补全命令和选项：

``shell

补全命令选项

httptap –

显示：–method, –data, –follow, –timeout, –no-http2, –ignore-ssl, –cacert, –proxy, –header, –compact, –metrics-only, –json, –version, –help

输入部分选项后补全

httptap –fol

补全为：httptap –follow

补全多个选项

httptap –follow –time

补全为：httptap –follow –timeout

``

快速开始

基本 GET 请求

运行单个请求并显示富水瀑布：

shell httptap https://httpbin.io/get

带数据的 POST 请求

发送 JSON 数据（自动检测 Content-Type）：

shell httptap https://httpbin.io/post --data '{"name": "John", "email": "[email protected]"}'

注意： 当提供 --data 且未指定 --method 时，httptap 会自动切换为 POST（类似 curl）。

兼容 curl 的参数： httptap 接受最常见的 curl 语法，因此你常常可以直接用 httptap 替换 curl。别名包括 -X/--request 对应 --method，-L/--location 对应 --follow，-m/--max-time 对应 --timeout，-k/--insecure 对应 --ignore-ssl，-x 对应 --proxy，以及 --http1.1 对应 --no-http2。（并非每个 curl 选项都支持——替换命令时请仅使用这些共享参数。）

从文件加载数据：

shell httptap https://httpbin.io/post --data @payload.json

显式指定方法（绕过自动 POST）：

shell httptap https://httpbin.io/post --method POST --data '{"status": "active"}'

其他 HTTP 方法

PUT 请求：

shell httptap https://httpbin.io/put --method PUT --data '{"key": "value"}'

PATCH 请求：

shell httptap https://httpbin.io/patch --method PATCH --data '{"field": "updated"}'

DELETE 请求：

shell httptap https://httpbin.io/delete --method DELETE

自定义请求头

添加自定义请求头（重复使用 -H 可设置多个值）：

shell httptap \ -H "Accept: application/json" \ -H "Authorization: Bearer super-secret" \ https://httpbin.io/bearer

重定向与 JSON 导出

跟随重定向链并将指标转储为 JSON：

shell httptap --follow --json out/report.json https://httpbin.io/redirect/2

输出模式

收集适合日志的紧凑（单行）计时信息：

shell httptap --compact https://httpbin.io/get

为脚本暴露原始指标：

shell httptap --metrics-only https://httpbin.io/get | tee timings.log

高级用法

编程方式使用的用户可以为高级场景注入自定义执行器。如果你需要更改请求的执行方式（例如接入不同的 HTTP 栈或添加追踪），请提供你自己的 RequestExecutor 实现。

TLS 证书选项

排查自签名端点时绕过 TLS 验证：

shell httptap --ignore-ssl https://self-signed.badssl.com

该参数会禁用证书验证，并放宽许多握手约束，使传统端点（过期/自签名/主机名不匹配、弱哈希、较旧 TLS 版本）仍能完成握手。某些已从现代 OpenSSL 构建中移除的算法（例如 RC4 或 3DES）可能仍然不可用。请仅在可信网络上使用此模式。

为内部 API 使用自定义 CA 证书包：

shell httptap --cacert /path/to/company-ca.pem https://internal-api.company.com

当测试使用自定义证书颁发机构（CA）签发的证书、且该 CA 不在系统默认信任库中时，此选项非常有用。--cacert 选项（也可写作 --ca-bundle）接受 PEM 格式 CA 证书包的路径。

注意： --ignore-ssl 和 --cacert 互斥。使用 --ignore-ssl 可禁用所有验证，使用 --cacert 则使用自定义 CA 包进行验证。当使用 --cacert 时，CLI 输出会以 TLS CA: custom bundle 标记连接，JSON 导出中包含 network.tls_custom_ca: true，以便自动化检测自定义信任配置。

通过 HTTP/SOCKS 代理路由流量（显式覆盖优先于环境变量 HTTP_PROXY、HTTPS_PROXY、NO_PROXY）：

shell httptap --proxy socks5h://proxy.local:1080 https://httpbin.io/get

忽略所有代理环境变量并直接连接：

shell httptap --proxy "" https://httpbin.io/get

输出和 JSON 导出会包含代理 URI 及其来源，以便你确认实际使用的路径（例如 (from arg --proxy)、(from env HTTPS_PROXY)、(bypassed by env no_proxy)）。

SLO 阈值检查

使用 --slo KEY=MS[,KEY=MS...] 基于各阶段延迟预算把关 CI 任务、定时探针和 Kubernetes 就绪检查：

shell httptap --slo total=500,ttfb=200 https://api.example.com/health

• 当所有阈值均通过时，退出码为 0。
• 当最终成功步骤（不评估中间重定向）中至少有一个阈值被超过时，退出码为 4。
• 当规范格式错误（未知键、重复键、非正值、语法错误）时，退出码为 64。
• 始终渲染完整的水瀑布 / 紧凑 / JSON 输出，以便保留回归证据。

支持的键：dns、connect、tls、ttfb、wait、xfer、total。

输出扩展：

• 富 / 紧凑模式 — 水瀑布之后会显示一个带边框的面板，列出阈值和任何违规（实际值、阈值、超出的时间）。
• --metrics-only — 最终成功步骤携带 slo=pass 或 slo=fail slo_violations= 标记。
• --json — summary.slo 块包含 pass、thresholds_ms 以及每个违规的 {key, threshold_ms, actual_ms, delta_ms}。

``shell

CI 把关 — 仅在 SLO 违规时失败，容忍瞬时网络错误

httptap –slo total=2000,tls=300,ttfb=800 https://staging.example.com/ case $? in 0) echo “healthy” ;; 4) echo “SLO violation”; exit 1 ;; 75) echo “network flake, retrying later” ;; esac ``

完整规范、评估规则和示例：docs.httptap.dev/usage/slo (https://docs.httptap.dev/usage/slo/)。

环境变量

httptap 在运行时读取以下环境变量。它们都可以通过 CLI 参数覆盖，并且每个请求实际使用的来源都会记录在输出和 JSON 导出中。

代理配置的优先级：显式 -x/--proxy → --proxy ""（禁用环境变量）→ HTTPS_PROXY/HTTP_PROXY/ALL_PROXY（按协议匹配）→ NO_PROXY 排除 → 直接连接。

退出码

httptap 遵循 BSD sysexits.h 约定，因此可以干净地集成到 shell 管道、CI 任务和 systemd 服务中。

示例 — 仅在用法错误时让 CI 任务失败，容忍瞬时网络问题：

shell httptap --metrics-only https://api.example.com/health rc=$? if [ "$rc" = 64 ] || [ "$rc" = 70 ]; then exit "$rc" fi

发布

先决条件

• 必须在仓库设置中配置 GitHub Environment pypi
• 为 ozeranskii/httptap 配置 PyPI Trusted Publishing

步骤

1. 从 GitHub Actions 触发 Release 工作流：
   • 提供精确版本（例如 0.3.0），或
   • 选择 bump 类型：patch、minor 或 major
2. 该工作流将：
   • 使用 uv version 更新 pyproject.toml 中的版本
   • 使用 git-cliff 生成变更日志并更新 CHANGELOG.md
   • 提交更改并创建 git 标签
   • 在打标签的版本上运行完整测试套件
   • 构建 wheel 和源码分发包
   • 通过 Syft 生成 CycloneDX 和 SPDX 格式的 SBOM
   • 附加当前的 OpenVEX 文档（.vex/httptap.openvex.json）
   • 通过 Trusted Publishing (OIDC) 发布到 PyPI
   • 创建 GitHub Release，附上 wheel、sdist、SBOM 和 VEX 资产

示例输出

sample-output.png

重定向摘要包含总计行：

sample-follow-redirects-output.png

JSON 导出结构

json { "initial_url": "https://httpbin.io/redirect/2", "total_steps": 3, "steps": [ { "url": "https://httpbin.io/redirect/2", "st