API Debug

API Debug — API 调试实战指南

从请求构造到问题定位的完整 API 调试技能。

Goal

API 调试实战指南，包含请求构造、响应分析、问题定位、性能诊断、安全测试

Trigger

• 用户要求"调试API"、"测试接口"
  • API 返回异常需要排查
  • 需要构造复杂请求

调试流程

问题描述 → 请求构造 → 发送请求 → 响应分析 → 问题定位 → 修复验证

请求构造

curl 进阶用法

# 基础 GET
curl https://api.example.com/users

# POST JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"张三","email":"zhangsan@example.com"}'

# 带认证
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.example.com/users/me

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

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

# 文件上传
curl -X POST https://api.example.com/upload \
  -F "file=@./photo.jpg" \
  -F "description=Profile photo"

# 下载文件
curl -O https://api.example.com/files/report.pdf

# 超时设置
curl --connect-timeout 5 --max-time 30 https://api.example.com

# 重试
curl --retry 3 --retry-delay 2 https://api.example.com

# 保存响应头
curl -D headers.txt https://api.example.com

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

# 忽略 SSL 证书（调试用）
curl -k https://self-signed.example.com

# 详细调试
curl -v https://api.example.com 2>&1 | head -50

httpie 更友好

# GET
http https://api.example.com/users

# POST（自动 JSON）
http POST https://api.example.com/users \
  name=张三 email=zhangsan@example.com

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

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

# 上传文件
http --form POST https://api.example.com/upload \
  file@./photo.jpg

# 下载
http --download https://api.example.com/files/report.pdf

# 只看响应头
http --headers https://api.example.com

# 详细输出
http --verbose https://api.example.com

响应分析

状态码速查

响应头分析

# 查看完整响应
curl -i https://api.example.com/users

# 重要响应头
Content-Type: application/json      # 响应格式
Cache-Control: max-age=3600         # 缓存策略
X-RateLimit-Remaining: 99           # 剩余请求次数
X-Request-Id: abc123                # 请求追踪 ID
Set-Cookie: session=xyz; HttpOnly   # Cookie 设置

JSON 处理

# 格式化 JSON
curl -s https://api.example.com/users | jq .

# 提取特定字段
curl -s https://api.example.com/users | jq '.data[].name'

# 过滤
curl -s https://api.example.com/users | jq '.data[] | select(.age > 18)'

# 统计
curl -s https://api.example.com/users | jq '.data | length'

# 转为 CSV
curl -s https://api.example.com/users | jq -r '.data[] | [.id, .name, .email] | @csv'

常见问题排查

1. 认证问题 (401)

# 检查 Token 是否存在
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me

# 解码 JWT
echo $TOKEN | cut -d'.' -f2 | base64 -d | jq .

# 检查 Token 过期时间
echo $TOKEN | cut -d'.' -f2 | base64 -d | jq '.exp | todate'

# 重新获取 Token
curl -X POST https://api.example.com/auth/login \
  -d '{"email":"user@example.com","password":"pass"}'

2. 权限问题 (403)

# 检查用户角色
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me | jq '.role'

# 检查所需权限
# 查看 API 文档或后端代码

3. 参数问题 (400/422)

# 检查请求体
curl -v -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"","email":"invalid"}' 2>&1

# 查看详细错误
curl -s -X POST https://api.example.com/users \
  -d '{"name":"","email":"invalid"}' | jq '.error.details'

4. 网络问题

# DNS 解析
nslookup api.example.com
dig api.example.com

# 连接测试
telnet api.example.com 443

# 路由追踪
traceroute api.example.com

# SSL 证书检查
openssl s_client -connect api.example.com:443 -servername api.example.com

5. 性能问题

# 测量响应时间
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://api.example.com

# 多次测量取平均
for i in {1..10}; do
  curl -o /dev/null -s -w "%{time_total}\n" https://api.example.com
done | awk '{sum+=$1} END {print sum/NR}'

调试工具对比

快速使用

# 调试 401 错误
我的 API 返回 401，帮我排查

# 构造复杂请求
帮我构造一个带文件上传和认证的 POST 请求

# 分析响应
这个 API 响应很慢，帮我分析原因

# 测试认证流程
帮我测试完整的登录-访问-刷新 Token 流程

参考资料

• curl 完整用法: references/curl.md
• httpie 用法: references/httpie.md
• HTTP 状态码: references/status-codes.md
• jq 处理: references/jq.md