用 CLI 调试 HTTP API

---
name: debug-http-api-workflow
description: "先用明确的方法、Header、Body、超时和保存的响应复现单个请求，再改客户端或服务端。"
---

# 调试 HTTP API

## 适用目标

判断问题来自网络、认证、请求形状、服务端行为还是响应解析。

## 证据边界

- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。

## 推荐工具、安装与认证

- **curl**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 8.7.1）
  - 安装：`brew install curl`
  - 认证：none, basic, bearer token, client certificate, netrc
  - 最小权限：通过环境变量提供范围受限的 Token，不要在输出中打印请求密钥。
- **HTTPie**（证据：`docs-verified`，文档检查：`2026-07-10`，未记录独立执行版本）
  - 安装：`pipx install httpie`
  - 认证：none, basic, bearer token, auth plugins, sessions
  - 最小权限：通过环境变量提供请求头，并把 session 存储在仓库之外。
- **jq**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 jq-1.7.1-apple）
  - 安装：`brew install jq`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。

## 输入合同

- Endpoint 与方法
- 脱敏 Header
- 请求体
- 预期状态与响应形状

## 输出合同

- 可复现命令
- 状态与 Header
- 保存的响应体
- 故障假设

## 安全工作流

1. **构造安全复现** — 认证值从环境读取，并设置明确超时。
   - 输入: Endpoint、方法、Header 和 Body
   - 输出: 可审查请求命令
   - 风险: `read-only`
   - 命令: `curl --fail-with-body --max-time 20 -D headers.txt -o response.json "$API_URL"`
2. **捕获响应** — 分别保存 Header 和 Body，再解析 JSON，不输出凭证。
   - 输入: HTTP 响应
   - 输出: 状态、Header、解析结果与退出码
   - 风险: `local-write`
   - 命令: `jq . response.json`
3. **对比并隔离** — 每次只修改一个输入，区分客户端、服务端与网络故障。
   - 输入: 基线请求和预期合同
   - 输出: 最小失败案例和可能故障层
   - 风险: `read-only`

## 必须先确认

- 调用创建、修改、删除、扣费、发送或部署的接口
- 使用生产凭证或客户数据
- 重试非幂等请求

## 回滚

- 基线优先使用只读 endpoint
- 删除含敏感数据的本地响应文件
- 批准写入前先记录资源 ID 和文档定义的反向操作

## 官方来源

- [curl manual](https://curl.se/docs/manpage.html) — 用于核对当前命令、认证、输出和操作边界。
- [HTTPie CLI documentation](https://httpie.io/docs/cli) — 用于核对当前命令、认证、输出和操作边界。
- [jq manual](https://jqlang.github.io/jq/manual/) — 用于核对当前命令、认证、输出和操作边界。