API 测试与调试

这页适合作为“接口联调与排障工具箱”。核心不是工具越多越好，而是知道什么时候该用命令行、什么时候用 GUI、什么时候把请求直接写进仓库里做长期维护。

先按场景选工具

• 快速复现一个请求：优先 curl
• 命令更友好、结果更易读：优先 HTTPie
• 需要团队共享请求集和环境变量：优先 Bruno
• 需要复杂集合、脚本和协作生态：可用 Postman
• 想和代码一起版本管理：优先 .http 文件或 Bruno

curl

最通用的命令行 HTTP 客户端。

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

# 带 Header
curl -H "Authorization: Bearer TOKEN" https://api.example.com/users

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

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

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

# 查看响应头
curl -I https://example.com

# 详细输出（调试）
curl -v https://example.com

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

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

# 使用代理
curl -x http://127.0.0.1:7890 https://example.com

PowerShell 中使用

# PowerShell 的 curl 是 Invoke-WebRequest 的别名
# 使用真正的 curl 需要 curl.exe
curl.exe -s https://api.example.com/users | ConvertFrom-Json

HTTPie

更友好的命令行 HTTP 客户端：

pip install httpie

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

# POST
http POST https://api.example.com/users name=Domi email=[email]

# 带 Header
http https://api.example.com/users Authorization:"Bearer TOKEN"

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

GUI 工具

Bruno

开源 API 客户端，集合保存在本地文件系统（Git 友好）：

scoop install bruno

• 项目：GitHub

Postman

最流行的 API 测试工具：

winget install Postman.Postman

Insomnia

轻量级 REST 客户端：

winget install Insomnia.Insomnia

VS Code 扩展

REST Client 示例

创建 api.http 文件：

### 获取用户列表
GET https://api.example.com/users
Authorization: Bearer {{token}}

### 创建用户
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "Domi",
  "email": "[email]"
}

### 变量定义
@token = your-api-token
@baseUrl = https://api.example.com

常用测试 API

推荐排障顺序

调接口时，比较稳的顺序通常是：

1. 先确认 URL、方法、Header、Body 是否正确
2. 再看响应状态码和响应体
3. 再检查鉴权、代理、环境变量、CORS 或网关
4. 最后再回到服务端日志和代码层面

很多接口问题其实在请求层就能看出来，不一定要第一时间进 IDE。

常见问题

本地能调，前端里调不通

高频原因通常包括：

• CORS
• Cookie / 凭据没带上
• 代理配置不同
• 前端环境变量指向了错误地址

Postman 能通，curl 不通

这通常说明：

• Header 没带全
• Body 编码格式不同
• 重定向、代理、证书校验或认证方式存在差异

请求很多，维护越来越乱

这时更推荐：

• 把通用环境变量抽出来
• 命名规范统一
• 长期调试用 Bruno / .http 文件进仓库

延伸阅读

• RESTful API 设计
• Chrome DevTools 技巧
• 前端测试指南

参考链接

• curl 文档 — 官方文档
• HTTPie 文档 — 官方文档
• Bruno — 官网