用 curl 调试 API:5 个常用选项

举报
yd_243701064 发表于 2026/11/14 06:13:33 2026/11/14
【摘要】 curl 是调试 API 的利器。本文介绍 -i 看响应头、-X 指定方法、-H 加请求头、-d 发 JSON、-o 保存结果和 -w 看耗时这 5 个常用选项,每个选项都给出可在 httpbin 上运行的示例,最后附一份联调调试清单。

调接口时最怕一句话:明明本地能跑,一到联调就报错。多数时候问题不在代码,而在请求本身——方法错了、请求头少了、参数没发过去。打开浏览器抓包太重,写一段代码又太慢,这时候 curl 最顺手:它随系统自带,不用装客户端,一条命令就能把请求发出去、把响应看明白。本文用 5 个常用选项,带你把 curl 当成日常调试工具。

curl 是什么

curl 是一个命令行工具,用来向服务器发送请求并显示响应。它支持 HTTP、HTTPS 等多种协议,Linux 和 macOS 一般自带,Windows 10 之后也可以直接用。它的好处是“所见即所得”:你写什么请求,它就原样发什么请求,服务器回什么,它就原样给你看什么。联调时先在终端跑通,再去写代码,能少走很多弯路。

1. -i:先看响应头

只看返回内容不够,状态码和响应头里往往藏着真相。-i 会把响应头和响应体一起打印出来:

curl -i https://httpbin.org/get

你会先看到 HTTP/2 200 这样的状态行,再看到 Content-Type: application/json 等响应头,最后才是返回的 JSON。遇到 301 跳转、401 未授权、500 服务错误时,先看这一行,比猜测快得多。

2. -X:指定请求方法

默认情况下 curl 发的是 GET 请求。想发 POST、PUT、DELETE,就用 -X 指定方法:

curl -X POST https://httpbin.org/post

注意,-X 只是改了方法名,不会自动帮你带上请求体。真正发数据要配合下面讲的 -d。另外提醒一句:只改方法、不改语义的做法要小心,比如对一个只接受 GET 的接口发 POST,服务器很可能直接返回 405。

3. -H:加上请求头

很多接口要求带上特定的请求头,比如 Authorization 做鉴权、Accept 声明想要的返回格式。-H 可以重复使用,写几个就加几个:

curl -H "Authorization: Bearer demo-token" -H "Accept: application/json" https://httpbin.org/get

httpbin 会在返回的 JSON 里原样回显你发过去的请求头,方便核对:headers 字段里能看到 Authorization 和 Accept 是否真的发出去了。调试鉴权失败时,先检查这里——多一个空格、少一个 Bearer,都可能导致 401。

4. -d:发送 JSON 数据

-d 用来发送请求体。发 JSON 时要同时把 Content-Type 设为 application/json,并用单引号把整个 JSON 包起来,避免 shell 把双引号吃掉:

curl -X POST -H "Content-Type: application/json" -d '{"name": "xingyunzhou", "role": "developer"}' https://httpbin.org/post

返回的 JSON 里,json 字段就是服务器收到的对象,data 字段是原始字符串。两者对照一看,就知道数据有没有被正确解析。如果接口说“参数缺失”,先看看这里是不是少了字段、写错了字段名,或者 Content-Type 没设对。

5. -o 和 -w:保存结果并看耗时

返回内容太长时,直接打印会刷屏。用 -o 把响应保存到文件,终端就清爽了:

curl -o response.json https://httpbin.org/get

执行后当前目录下会出现 response.json,再用编辑器慢慢看。想进一步知道“慢在哪”,就用 -w 输出耗时,配合 -s 静默掉进度条:

curl -o /dev/null -s -w "HTTP 状态:%{http_code}\n总耗时:%{time_total}s\n" https://httpbin.org/get

其中 %{http_code} 是状态码,%{time_total} 是从发出请求到收完响应的总时间。接口变慢时,这一行能快速区分是网络慢还是服务端慢。

调试清单

下次接口不通时,按这个顺序过一遍:

  • [ ] 先用 -i 看状态码和响应头,确认是 2xx 还是 4xx、5xx
  • [ ] 检查 -X 的方法是否和接口文档一致
  • [ ] 用 -H 核对鉴权头和 Content-Type 是否带对
  • [ ] 用 -d 对照返回的 json 字段,确认参数没有少发、错发
  • [ ] 用 -o 保存大响应,再用 -w 看状态码和耗时

把这 5 个选项记熟,curl 就够应付大部分日常联调。先在 httpbin 上把每条命令亲手跑一遍,再去调真实接口,你会发现很多“玄学问题”其实只是请求没发对。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。