第 7 章 · 04 测服务:`curl`

第 7 章 · 04 测服务:curl

本节摘要:curl 是 HTTP 调试的瑞士军刀,也是测「服务可用性」最精准的工具。它直接对接 HTTP 协议,能让你看到状态码(200/301/404/500)、响应头、握手过程、重定向链——这些都是浏览器为「友好」而隐藏的细节。本节要讲清 curl 在接口调试中的核心用法:自定义方法/头/体、-v 看握手、-i 看响应头、-o 存文件、--max-time 防卡死,以及如何用它的退出码做脚本里的健康检查。掌握 curl,你调试 API 比用图形化工具更快。

内容来源:综合 curl 知识整理,套用体系化模板。

学习目标

阅读完本节,你应当能够:

1. 用 curl URL 发起 GET 请求,理解它默认打印响应体到 stdout。
2. 用 -X 改方法、-H 加头、-d 发体,构造 POST/PUT 等请求。
3. 用 -i 显示响应头、-v 详细看握手与请求/响应全过程。
4. 用 -o 存响应到文件、-L 自动跟重定向、--max-time 设超时。
5. 解读 HTTP 状态码:2xx 成功、3xx 重定向、4xx 客户端错、5xx 服务端错。
6. 用 curl 的退出码在脚本里做健康检查(curl -sf URL 失败即非 0)。

一、设计动机:为什么测服务用 curl 而不是浏览器

服务部署后,「用浏览器访问一下」是最直觉的验证方式。但浏览器在「友好」的同时也「隐藏」了很多关键信息:

• 状态码 301/302 重定向,浏览器自动跟随,你看不到中间过程。
• 响应头(如 Content-Type、Set-Cookie)被折叠。
• 证书错误浏览器弹个框,你看不到握手细节。
• 想发个 POST、改个头,浏览器操作起来麻烦。

curl 直接对接 HTTP 协议,把这些细节全暴露给你。它是「把 HTTP 当文本看」的工具——你能看到原始的请求行、头、体,以及响应的完整内容。这正是调试 API 需要的精度。

二、高频组合与实战

基础:GET 请求

curl http://example.com             # GET, 打印响应体到 stdout
curl -i http://example.com          # -i: 显示响应头(含状态行) + 体
curl -I http://example.com          # -I: 只看响应头(HEAD 请求), 不下载体
curl -L http://example.com          # -L: 自动跟随重定向(3xx)
curl -o page.html http://example.com   # -o: 响应存文件, 不打印
​

看握手与全过程:-v

curl -v http://example.com
​

-v(verbose)打印完整过程,前缀含义:

• > 开头:curl 发出的请求行与头。
• < 开头:服务器返回的响应行与头。
• * 开头:curl 自己的信息(DNS、连接、TLS 握手)。

*   Trying 93.184.216.34:80...
* Connected to example.com
> GET / HTTP/1.1
> Host: example.com
>
< HTTP/1.1 200 OK
< Content-Type: text/html
<
(响应体)
​

排查「连不上、握手失败、证书问题」必用 -v,它把问题暴露在哪个环节一清二楚。

构造 POST/PUT 请求

curl -X POST http://api.com/users                    # POST 空体
curl -X POST -d 'name=alice' http://api.com/users    # 表单体(application/x-www-form-urlencoded)
curl -X POST -H 'Content-Type: application/json' \
     -d '{"name":"alice"}' http://api.com/users      # JSON 体
curl -X POST -d @data.json http://api.com/users      # 体从文件读
​

加请求头

curl -H 'Authorization: Bearer xxx' http://api.com/me    # 加认证头
curl -H 'Accept: application/json' http://api.com/users   # 指定期望响应格式
​

超时与脚本友好

curl --max-time 5 http://example.com      # 最多等 5 秒(防卡死)
curl --connect-timeout 3 http://...       # 连接阶段最多 3 秒
curl -sf http://example.com               # -s 静默 -f 失败(HTTP 错)时退出码非0
# 在脚本里判断服务健康:
if curl -sf http://localhost:8080/health; then
    echo "服务正常"
else
    echo "服务异常(curl 退出码 $?)"
fi
​

三、解读 HTTP 状态码

curl -i/-v 会显示状态码,它是「服务到底怎么了」的精确判据:

💡 技巧:4xx 是「你请求得不对」,5xx 是「服务自己挂了」。排查时先看状态码类别,能快速锁定问题方向。502/504 通常是反向代理(Nginx)连不上后端;500 通常要看后端日志。

四、curl 的退出码

curl 的退出码(用 $? 看)极有用,是脚本做健康检查的依据:

脚本里用 curl -sf(静默 + 失败返回非 0)做健康检查最简洁。

五、踩坑与排错

坑 1:没加 -L,被重定向绕晕

curl http://example.com        # 返回一堆 301 重定向 HTML
curl -L http://example.com     # -L 自动跟重定向到最终内容
​

很多 URL 会重定向(如 http→https),不加 -L 看到的是重定向页面而非目标内容。

坑 2:卡住不返回,忘了超时

curl http://slow-server.com     # 可能一直卡住
curl --max-time 5 http://...    # 务必加超时, 尤其是脚本里
​

脚本里的 curl 必须加 --max-time,否则一个慢服务能让整个脚本卡死。

坑 3:JSON 体没加引号被 Shell 吃掉

curl -d {"name":"alice"} ...        # 错! {} 被 Shell 解释
curl -d '{"name":"alice"}' ...      # 对! 单引号保护 JSON
​

JSON 体里的 {、"、空格会被 Shell 特殊处理,始终用单引号包裹整个 JSON。

本节要点回顾

1. curl 是 HTTP 调试瑞士军刀,把请求/响应/握手细节全暴露,比浏览器更适合调 API。
2. 核心选项:-i(响应头)、-I(只看头)、-v(全过程握手)、-X(方法)、-H(头)、-d(体)、-o(存文件)、-L(跟重定向)。
3. 状态码:2xx 成功、3xx 重定向、4xx 客户端错(你的问题)、5xx 服务端错(服务的问题)。
4. 退出码极有用:-sf 配合 $? 是脚本健康检查的标准写法;7=端口没开、28=超时、22=HTTP错。
5. 脚本里的 curl 必加 --max-time,防慢服务卡死;JSON 体务必单引号包裹。

下一节讲 curl 的「下载向」兄弟——wget,它在大文件下载与递归镜像上更顺手。