HTTP 协议详解教程 / 第 17 章：调试与测试工具

第 17 章：调试与测试工具

掌握 HTTP 调试工具是排查网络问题、测试 API 的必备技能。本章介绍最常用的 HTTP 调试工具及其使用技巧。

17.1 curl — 命令行 HTTP 客户端

基础用法

# GET 请求
curl https://api.example.com/users

# 显示响应头
curl -i https://api.example.com/users

# 仅显示响应头
curl -I https://api.example.com/users

# 显示详细信息（握手、头部等）
curl -v https://api.example.com/users

# 静默模式（不显示进度）
curl -s https://api.example.com/users

# 美化 JSON 输出
curl -s https://api.example.com/users | jq .

请求方法与数据

# POST JSON
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"name":"Alice","age":30}' \
     https://api.example.com/users

# PUT 更新
curl -X PUT \
     -H "Content-Type: application/json" \
     -d '{"name":"Alice Updated"}' \
     https://api.example.com/users/1

# PATCH 部分更新
curl -X PATCH \
     -H "Content-Type: application/json" \
     -d '{"age":31}' \
     https://api.example.com/users/1

# DELETE 删除
curl -X DELETE https://api.example.com/users/1

头部与认证

# 自定义头部
curl -H "Authorization: Bearer eyJhbG..." \
     -H "Accept: application/json" \
     -H "X-Request-ID: abc123" \
     https://api.example.com/users

# Basic 认证
curl -u username:password https://api.example.com/admin

# Cookie
curl -b "session=abc123" https://api.example.com/profile

# 保存 Cookie
curl -c cookies.txt https://api.example.com/login
curl -b cookies.txt https://api.example.com/profile

文件操作

# 文件下载
curl -O https://example.com/file.zip

# 指定文件名下载
curl -o output.zip https://example.com/file.zip

# 文件上传
curl -F "[email protected]" -F "description=My photo" https://api.example.com/upload

# 断点续传
curl -C - -O https://example.com/large-file.zip

高级技巧

# 测试 HTTP/2
curl --http2 -v https://example.com

# 测试 HTTP/3
curl --http3 -v https://example.com

# 限制响应时间
curl --max-time 10 https://slow-api.example.com

# 跟踪重定向
curl -L https://example.com/redirect

# 限制重定向次数
curl -L --max-redirs 5 https://example.com/redirect

# 保存完整请求响应
curl -v -o response.txt https://api.example.com/data 2> headers.txt

# 使用代理
curl -x http://proxy:8080 https://example.com

# 忽略 SSL 证书错误（仅测试）
curl -k https://self-signed.example.com

# 并发请求（curl 7.66+）
curl --parallel \
     --parallel-max 5 \
     https://api.example.com/users \
     https://api.example.com/posts \
     https://api.example.com/comments

17.2 httpie — 人性化的 HTTP 客户端

安装

# pip
pip install httpie

# macOS
brew install httpie

# Ubuntu
apt install httpie

基础用法

# GET 请求（默认）
http https://api.example.com/users

# POST JSON（自动设置 Content-Type）
http POST https://api.example.com/users name=Alice age:=30

# 注意：字符串不用引号，数字用 :=

# PUT 更新
http PUT https://api.example.com/users/1 name="Alice Updated"

# DELETE
http DELETE https://api.example.com/users/1

语法优势

# curl 的写法
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"name":"Alice","age":30}' \
     https://api.example.com/users

# httpie 的写法（简洁得多）
http POST https://api.example.com/users name=Alice age:=30

高级功能

# 认证
http -a username:password https://api.example.com/admin

# Bearer Token
http https://api.example.com/users Authorization:"Bearer token123"

# 自定义头部
http https://api.example.com/users \
     X-Request-ID:abc123 \
     Accept:application/json

# 上传文件
http --form POST https://api.example.com/upload \
     [email protected] \
     description="My photo"

# 下载文件
http --download https://example.com/file.zip

# 只显示响应头
http --headers https://api.example.com/users

# 只显示响应体
http --body https://api.example.com/users

# 输出格式化
http --pretty=all https://api.example.com/users

# 会话保持（自动管理 Cookie）
http --session=mysession https://api.example.com/login \
     username=alice password=secret
http --session=mysession https://api.example.com/profile

# 调试模式
http --verbose https://api.example.com/users

17.3 浏览器 DevTools

Network 面板

Chrome DevTools 的 Network 面板是最常用的 HTTP 调试工具。

打开方式

Windows/Linux: F12 或 Ctrl+Shift+I → Network 标签
macOS: Cmd+Option+I → Network 标签

核心功能

功能	说明
请求列表	显示所有网络请求
过滤	按类型（XHR、JS、CSS、图片）过滤
请求详情	点击请求查看详细信息
时序图	查看请求生命周期
Waterfall	可视化请求时序

请求详情标签

标签	内容
Headers	请求/响应头部
Preview	响应预览
Response	响应原始内容
Cookies	Cookie 信息
Timing	时序详情

常用操作

// 在 Console 中过滤请求
// 按 URL 过滤
// 在 Filter 输入框输入: api.example.com

// 按状态码过滤
// status-code:404

// 按方法过滤
// method:POST

// 按资源类型过滤
// 点击 XHR、Fetch、JS、CSS 等按钮

导出 HAR 文件

1. 右键点击请求列表
2. 选择 "Save all as HAR with content"
3. 保存 .har 文件（可用于分享、分析）

17.4 Wireshark — 网络抓包

安装与基础

# Ubuntu
sudo apt install wireshark

# macOS
brew install --cask wireshark

# 启动（需要 root 权限抓取网络包）
sudo wireshark

常用过滤器

# HTTP 过滤
http
http.request
http.response
http.request.method == "GET"
http.request.method == "POST"

# 按主机过滤
http.host == "api.example.com"

# 按状态码过滤
http.response.code == 200
http.response.code >= 400

# 按 Content-Type 过滤
http.content_type contains "json"

# HTTPS/TLS 过滤
tls
tls.handshake

# TCP 过滤
tcp.port == 443
tcp.stream == 0

分析 HTTP 请求

1. 启动 Wireshark，选择网络接口
2. 设置过滤器: http.host == "api.example.com"
3. 在浏览器中执行操作
4. 查看抓包结果

# 请求详情:
- Frame: 物理层信息
- Ethernet: 数据链路层
- IP: 网络层
- TCP: 传输层
- HTTP: 应用层（明文 HTTP 可见）
- TLS: 加密内容（HTTPS 只能看到握手）

TLS 解密

# 设置 SSL Key Log 文件
# 环境变量 SSLKEYLOGFILE
export SSLKEYLOGFILE=~/sslkeys.log

# Chrome/Firefox 会自动记录 TLS 密钥到此文件

# Wireshark 中设置:
# Edit → Preferences → Protocols → TLS → (Pre)-Master-Secret log filename
# 选择 ~/sslkeys.log

# 现在可以解密 HTTPS 流量

17.5 其他实用工具

httpstat — 可视化请求时序

# 安装
pip install httpstat

# 使用
httpstat https://api.example.com/users

# 输出示例：
#   DNS Lookup   TCP Connection   TLS Handshake   Server Processing   Content Transfer
# [     12ms    |      23ms      |     45ms      |       67ms        |       12ms       ]
#              |                |               |                   |                  |
#         namelookup:12ms   connect:35ms    pretransfer:80ms    starttransfer:147ms   total:159ms

ngrok — 本地服务暴露

# 安装
brew install ngrok

# 暴露本地服务
ngrok http 3000

# 输出:
# Forwarding  https://abc123.ngrok.io -> http://localhost:3000

# 测试 Webhook
ngrok http 3000 --subdomain=myapp

mitmproxy — 中间人代理

# 安装
pip install mitmproxy

# 启动代理
mitmproxy

# 默认监听 8080 端口
# 配置浏览器使用 127.0.0.1:8080 作为代理

# 查看请求: 在界面中浏览、过滤、查看请求详情
# 修改请求: 按 e 编辑请求
# 重放请求: 按 r 重放

17.6 API 测试工具

Postman

功能	说明
请求构建	可视化构建 HTTP 请求
环境变量	不同环境（开发/测试/生产）
测试脚本	JavaScript 编写自动化测试
集合运行	批量运行 API 测试
Mock 服务器	模拟 API 响应

Insomnia

功能	说明
轻量级	比 Postman 更轻便
GraphQL	原生支持 GraphQL
插件	丰富的插件生态
Git 集成	请求定义可版本控制

17.7 业务场景：排查 API 问题

场景：API 返回 401

# 1. 检查请求头是否正确
curl -v -H "Authorization: Bearer <token>" https://api.example.com/users

# 2. 检查 Token 是否过期
echo "eyJhbGciOiJIUzI1NiIs..." | cut -d. -f2 | base64 -d 2>/dev/null | jq .

# 3. 检查 Token 内容
# exp 字段是过期时间（Unix 时间戳）
# 检查是否已过期

场景：CORS 错误

# 1. 发送预检请求
curl -X OPTIONS \
     -H "Origin: https://frontend.example.com" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: Content-Type" \
     -v https://api.example.com/users

# 2. 检查响应头部
# Access-Control-Allow-Origin: *
# Access-Control-Allow-Methods: GET, POST, PUT, DELETE
# Access-Control-Allow-Headers: Content-Type

场景：性能问题

# 1. 测量各阶段耗时
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nFirst Byte: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://api.example.com/users

# 2. 使用 httpstat 可视化
httpstat https://api.example.com/users

# 3. 检查是否使用了缓存
curl -I https://api.example.com/users
# 检查 Cache-Control、ETag、Last-Modified

⚠️ 注意事项

不要在生产环境记录敏感数据：调试时注意隐藏 Token、密码等
Wireshark 需要权限：抓包需要管理员/root 权限
TLS 解密：需要设置 SSLKEYLOGFILE 环境变量
代理工具安全：mitmproxy 等会拦截所有流量，测试完记得关闭
curl 的 -k 选项：仅在测试时使用，不要在生产环境禁用证书验证

🔗 扩展阅读

下一章：第 18 章：API 设计最佳实践 — RESTful 规范、版本控制、错误处理、限流、幂等性