基础用法¶
命令行界面¶
httptap 命令行界面提供了多种选项，用于自定义你的 HTTP 请求和输出。
语法¶
选项¶
兼容 curl： 常见的 curl 参数可作为别名接受。将
curl替换为httptap，并继续使用你熟悉的选项，如-X/--request、-L/--location、-m/--max-time、-k/--insecure、-x以及--http1.1；-f/--fail、-4/--ipv4、-6/--ipv6和--resolve与 curl 中的名称相同。这并非完整的 curl 克隆——请只使用此处列出的共有参数。
请求选项¶
-X, --request, --method METHOD¶
指定要使用的 HTTP 方法。支持的方法：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。
方法名不区分大小写。
兼容 curl 的别名： -X、--request。
默认行为： - 未提供 --data：默认为 GET - 提供了 --data 但没有 --method：自动切换为 POST（类似 curl） - 显式指定 --method：遵循所指定的方法
-d, --data DATA¶
发送请求体数据。可以是内联字符串，也可以使用 @filename 语法引用文件。
内联 JSON 数据：
从文件加载：
内联数据会按参数的原始字节发送，与 curl 相同；在 POSIX 系统上，这也包括不是有效 UTF-8 的参数。
自动检测： - 自动检测 Content-Type（JSON、XML、纯文本） - 首先检查文件扩展名（.json、.xml、.txt） - 回退到 JSON 校验
不同方法的示例：
# POST（存在 --data 时自动检测）
httptap --data '{"key": "value"}' https://httpbin.io/post
# PUT
httptap --method PUT --data '{"status": "updated"}' https://httpbin.io/put
# PATCH
httptap --method PATCH --data '{"field": "modified"}' https://httpbin.io/patch
# 带请求体的显式 GET（不常见，会触发警告）
httptap --method GET --data 'query-data' https://httpbin.io/get
-H, --header¶
为请求添加自定义 HTTP 请求头。可多次使用。
httptap \
-H "User-Agent: MyApp/1.0" \
-H "Authorization: Bearer token123" \
https://httpbin.io/bearer
请求头名称必须是 HTTP token（字母、数字以及 !#$%&'*+-.^_`|~），值只能包含可打印 ASCII 字符、空格和制表符。违反这些规则的请求头，例如名称中含空格、值中含 CR、LF 或其他控制字符，或值中含非 ASCII 字符（httpx 以 ASCII 发送请求头的值），会在发出任何请求之前以退出码 64 被拒绝。错误信息会指出该请求头，但绝不会打印其值。
-L, --location, --follow¶
跟随 HTTP 重定向，并显示链中每一步的计时（最多 10 次重定向）。
兼容 curl 的别名： -L、--location。
默认情况下，httptap 不会跟随重定向，会在第一个重定向响应（3xx 状态码）处停止。
如果在跟随 10 次重定向之后响应仍是重定向，httptap 会停止、打印警告、在 JSON 导出中将该步骤标记为redirect_limit_reached: true，并以代码 47 退出。
跟随重定向时，httptap 采用与 curl 和浏览器相同的规则：
Authorization、Cookie和Proxy-Authorization请求头只发送到原始源（协议、主机和端口）。一旦重定向指向不同的源，后续整个重定向链都不再发送这些请求头；同一主机在默认端口上从http升级到https（80 → 443）时会保留。303 See Other，以及POST之后的301/302，会将下一个请求切换为不带请求体的GET。307和308保留原方法和请求体。
如果重定向的 Location 无法请求（端口无效或超出范围、缺少主机、协议不是 http/https、IPv6 字面量格式错误），3xx 步骤会被保留，重定向链以针对该目标的失败步骤结束，错误为 Invalid redirect target: …，httptap 以代码 75 退出。不使用 --follow 时，无论 Location 是什么，3xx 响应都按收到的原样报告。
Location URL 中的凭证（https://user:password@host/）在输出和 JSON 导出中会被遮蔽（https://user:****@host/），但跟随的仍是真实 URL。
-m, --max-time, --timeout SECONDS¶
如果总耗时超过指定的秒数，则中止请求链。
该限制是整个请求链（包括重定向）的硬性截止时间：DNS 解析、连接、等待响应和读取响应体共享这一时间，停滞或持续缓慢发送字节的服务器会在截止时被切断。此时该步骤以 Request timeout: total deadline exceeded 失败，httptap 以代码 75 退出。
兼容 curl 的别名： -m、--max-time。
默认超时为 20 秒。
--no-http2 / --http1.1¶
禁用 HTTP/2 协商并强制使用 HTTP/1.1 连接。
默认情况下，如果服务器支持则启用 HTTP/2。
兼容 curl 的别名： --http1.1。
-4, --ipv4 和 -6, --ipv6¶
将 DNS 解析和连接限制为 IPv4 或 IPv6。这两个选项互斥。
它们不能与 HTTP、HTTPS 或 SOCKS5H 代理同时使用，因为这些代理会自行解析目标主机名。
--resolve HOST:PORT:ADDR¶
将某个主机名和端口连接到指定的 IPv4 或 IPv6 地址，同时保留原始的 Host 请求头和 TLS SNI。这适用于在 DNS 切换前测试某一个后端，或绕过轮询（round-robin）DNS 记录。对于不同的主机和端口组合，该选项可重复使用。
httptap --resolve api.example.com:443:203.0.113.10 https://api.example.com/health
httptap --resolve api.example.com:443:[2001:db8::10] https://api.example.com/health
国际化主机名可以用任一形式匹配：为 bücher.example 设置的条目同样适用于 https://xn--bcher-kva.example/，反之亦然。httptap 以 IDNA 2008 形式（xn--…）解析这类名称，与它在 Host 请求头和 TLS SNI 中发送的名称相同。
--resolve 适用于直连和本地 DNS 解析的 SOCKS5 代理。HTTP、HTTPS 和 SOCKS5H 代理会在远端解析目标，因此将它们与 --resolve 组合使用会被拒绝，与 -4/-6 相同。
-k, --insecure, --ignore-ssl¶
禁用 TLS 证书校验。适用于调试自签名主机或已过期的证书。
Warning
请仅在可信网络中使用此选项。它会禁用证书校验并放宽握手约束。
兼容 curl 的别名： -k、--insecure。
-x, --proxy URL¶
通过指定的代理转发请求。支持 HTTP、HTTPS、SOCKS5 和 SOCKS5H 协议。
兼容 curl 的别名： -x。
# HTTP 代理
httptap --proxy http://proxy.local:8080 https://httpbin.io/get
# SOCKS5 代理（由代理解析 DNS）
httptap --proxy socks5h://proxy.local:1080 https://httpbin.io/get
# SOCKS5 代理（本地解析 DNS）
httptap --proxy socks5://proxy.local:1080 https://httpbin.io/get
# 忽略代理环境变量并直连
httptap --proxy "" https://httpbin.io/get
--proxy 参数优先于环境变量（HTTP_PROXY、HTTPS_PROXY、NO_PROXY）。使用 --proxy "" 可忽略所有代理环境变量并直连。有关代理协议、DNS 解析和环境变量配置的详细信息，请参见 高级功能。
代理 URL 中的凭证（http://user:password@proxy:3128，包括来自环境变量的代理）会用于建立连接，但在输出和 JSON 导出中会被遮蔽（http://user:****@proxy:3128）。
未带协议的代理（proxy.local:3128）会被视为 http://，与 curl 相同。格式错误的代理 URL（不支持的协议、缺少主机、端口无效或超出范围、未闭合的 IPv6 字面量）会在发出任何请求之前以退出码 64 被拒绝；错误信息中显示的 URL 会遮蔽密码。
--cacert, --ca-bundle PATH¶
使用自定义 CA 证书包（PEM 格式）进行 TLS 校验。适用于由私有 CA 签名的内部端点。
与 --ignore-ssl 互斥。
输出选项¶
--compact¶
以紧凑的单行格式显示结果，适合日志记录。
输出：
Step 1: 200 GET https://httpbin.io/get | dns=8.9ms connect=97.0ms tls=194.6ms ttfb=446.0ms total=447.3ms | 389 B
--compact 为每一步打印一行人类可读的信息（适合日志和重定向链追踪），同时仍会渲染分析头部和 Redirect Chain Summary 表格。响应大小会以适当的单位（B、KB、MB）显示。若需机器可解析的输出，请参见 --metrics-only。
--metrics-only¶
输出未经格式化的原始指标，非常适合脚本化和自动化。
输出：
Step 1: dns=30.1 connect=97.3 tls=199.0 ttfb=472.2 total=476.0 status=200 bytes=389 ip=44.211.11.205 family=IPv4 tls_version=TLSv1.2 proxy=direct
--json PATH¶
将完整的请求数据导出到 JSON 文件。使用 - 可改为将 JSON 写入 stdout；此时常规报告会被抑制，以便将输出通过管道传递。
如果文件无法写入，httptap 会以代码 73 退出。
该 JSON 文件包含：
- 所有阶段的计时明细
- 网络信息（IP 地址、TLS 详情、证书信息）
- 响应元数据（状态、请求头、响应体大小）
- 完整的重定向链（使用
--follow时） - SLO 评估（提供
--slo时）
--har PATH¶
将请求链导出为浏览器 DevTools 和 HAR 查看器可以打开的 HTTP Archive（HAR 1.2）文件。使用 - 可将其写入 stdout；此时常规报告会被抑制。--har 可以与 --json 同时使用，但只能有一个使用 -。
httptap --follow --har run.har https://httpbin.io/redirect/2
httptap --har - https://httpbin.io/get | jq '.log.entries[].timings'
如果文件无法写入，httptap 会以代码 73 退出。计时的对应关系以及 httptap 添加的字段请参见 HAR 导出。
--prometheus PATH¶
以 Prometheus textfile collector 格式写出各阶段计时。持续时间以 httptap_request_duration_seconds gauge 导出，带有 host、step 和 phase 标签，同时还会导出 httptap_request_success 和 httptap_last_run_timestamp_seconds；路径和查询字符串绝不会作为标签。
--otlp ENDPOINT¶
将本次运行导出为一条 OpenTelemetry trace：一个根 span、每个请求步骤一个 span，以及 DNS、连接、TLS、服务器等待和传输阶段的子 span。请先安装可选依赖：
--slo KEY=MS[,KEY=MS...]、--slo-file PATH¶
根据各阶段的延迟预算校验最终成功的步骤。发生违规时 httptap 仍会渲染完整报告，但会以代码 4 退出，以便该结果可作为 CI 任务、cron 探针或 Kubernetes 就绪检查的门禁。
httptap --slo total=500,ttfb=200 https://httpbin.io/get
# 每行一个阈值；内联值会覆盖文件中的值。
httptap --slo-file slo.txt --slo total=1000 https://httpbin.io/get
支持的键：dns、connect、tls、ttfb、wait、xfer、total。有关完整规范、退出码优先级以及 CI/cron 实用示例，请参见专门的 SLO 阈值校验 页面。
-f, --fail¶
当任一已完成的请求返回 HTTP 4xx 或 5xx 时以代码 22 退出，同时仍会渲染完整的计时报告并写出 --json 输出。网络和 TLS 故障保持其原有的、优先级更高的退出码。
--version¶
显示 httptap 版本并退出。
HTTP 方法¶
httptap 支持所有标准 HTTP 方法：
- GET —— 获取资源（未提供
--data时的默认方法） - POST —— 创建/提交资源（提供
--data时自动选用） - PUT —— 替换资源
- PATCH —— 部分更新资源
- DELETE —— 删除资源
- HEAD —— 仅获取请求头
- OPTIONS —— 查询允许的方法
方法选择逻辑¶
- 显式方法：
--method始终优先 - 自动 POST： 存在
--data而没有--method时，默认为 POST - 默认 GET： 未提供
--data或--method时，使用 GET
按使用场景分类的示例¶
API 测试：
# 创建资源
httptap --data '{"title": "New Post"}' https://httpbin.io/post
# 更新资源
httptap --method PUT --data '{"title": "Updated"}' https://httpbin.io/put
# 部分更新
httptap --method PATCH --data '{"status": "published"}' https://httpbin.io/patch
# 删除资源
httptap --method DELETE https://httpbin.io/delete
健康检查：
# 快速检查（仅请求头）
httptap --method HEAD https://httpbin.io/status/200
# 完整响应
httptap https://httpbin.io/status/200
请求流程¶
每次 httptap 请求都会经历以下阶段：
- DNS 解析 —— 域名查找
- TCP 连接 —— 建立 TCP 连接（通过 HTTP CONNECT 代理时：连接到代理并建立隧道）
- TLS 握手 —— 协商安全连接（仅 HTTPS）
- 服务器等待 —— 从请求发出到收到第一个响应字节之间的时间
- 响应体传输 —— 下载响应体
理解输出¶
丰富模式（默认）¶
默认的丰富输出会显示一个瀑布图表格，包含：
- 阶段名称和持续时间
- 可视化进度条
- 网络详情（IP、TLS 版本、证书信息）
- 响应元数据（状态、大小、
Server头、重定向目标）
计时明细¶
- DNS (ms) —— 将域名解析为 IP 地址的时间
- Connect (ms) —— 建立 TCP 连接的时间；通过 HTTP CONNECT 代理时还包括 CONNECT 往返，因此隧道建立不会计入服务器等待；当主机有多个地址且前面的地址连接失败时，花在这些地址上的时间也计入此处和 Total（与 curl 的
time_connect相同） - TLS (ms) —— TLS 握手的时间（仅 HTTPS）
- TTFB (ms) —— 首字节时间（包含服务器处理）
- Transfer (ms) —— 下载响应体的时间
- Total (ms) —— 端到端的请求耗时
网络信息¶
- IP 地址 —— 解析出的 IP 地址及其地址族（IPv4/IPv6）
- TLS 版本 —— 协议版本（TLS 1.2、TLS 1.3）
- 加密套件 —— 协商出的加密套件
- 证书 CN —— 服务器证书中的通用名称（Common Name）
- 证书到期 —— 证书到期前的剩余天数
示例¶
基础健康检查¶
带认证的 API 请求¶
httptap \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "Accept: application/json" \
https://httpbin.io/bearer