(科普文)curl＂可＂得一切

概述

前几天在群与“知名”技术博客芋道源码的作者芋艿、骚气的再见伐木机以及其他大佬们讨论了一个问题：通过哪些方式可以方便地测试 HTTP API，并且便于向他人分享 TEST CASE。

芋艿同学推荐使用 IDEA 的 HTTP Client 工具，然而我是一个命令行控，不太喜欢用各种 IDE、GUI 工具，比如 Chrome 的 Postman 插件、Rest HTTP Client 插件等，就连写 Python 代码也很少用 IDE。本文将介绍如何使用 CLI 工具 curl 来测试 HTTP API。

curl 是一个用于使用 URL 传输数据的命令行工具和类库，其功能非常强大，不仅可以完全地取代 Postman 之类的 GUI 工具，还提供很多高级功能。与他人协同排查问题时，只需要分享命令或脚本即可。

在开始介绍 curl 之前，将简单地介绍：

测试环境

HTTP 请求报文的格式

HTTP/1.X 请求的流程

测试环境

用于测试的 Python Web Server 的源代码在：Tim 的博客，它不依赖任何第三方框架，下载后，直接用 python 命令执行即可

curl 的版本是 7.59.0

HTTP 请求报文的格式

HTTP 请求报文的格式如下：

请求行CRLF请求头CRLF...请求头CRLFCRLF请求体

其中 CRLF 代表回车（CR，即 \r）加换行（LF，即 \n）。

请求行由使用空格分隔的三部分组成：

请求方法，比如 GET

URI，比如 /index.htm?from=timeline

协议/版本，比如 HTTP/1.1

请求头由使用冒号分隔的名称和值组成，比如：

User-Agent: curl/7.59.0

下面是一个 HTTP 请求报文的示例：

注：图片转载自：。

HTTP/1.X 请求的流程

解析域名，获得 IP 地址

建立 TCP 连接

发送 HTTP 请求报文

接收 HTTP 响应报文

关闭 TCP 连接

注：上面是未开启 Keep Alive 的请求流程

curl 的常用选项

下面我们将看到 curl 支持定制 HTTP 请求中的任意部分，也支持定制请求流程中的步骤。curl 的常用选项如下：

1，-X 用于指定请求方法，比如：

curl -X POST -d {"key": "value"} -H Content-Type: application/json :9090/post

2，-0 表示使用 HTTP 1.0，curl 默认使用 HTTP 1.1。比如：

curl -0 :9090/get

3，与主机名解析有关的选项

curl 通过 --dns-servers 选项支持：指定将要使用的 DNS 服务器的地址，该选项的值的格式是：

host[:port][,host[:port]]...

curl 通过 --connect-to 选项支持：连接到指定的主机和端口，而不是 URL 中的主机和端口，该选项的值的格式是：

HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT

其中 HOST 是请求中的主机，PORT 是请求中的端口，CONNECT-TO-HOST 是要连接到的主机名，CONNECT-TO-PORT 是要连接到的端口。

“connect to”中的主机和端口只被用于建立网络连接，不会影响用于 TLS/SSL 和应用层协议的主机和端口。

curl 通过 --resolve 选项支持：自定义主机名到 IP 地址的解析，该选项的值的格式是：

HOST:PORT:ADDRESS[,ADDRESS]...

其中 HOST 是 curl 将要尝试解析的主机名，PORT 是 curl 将要连接到的 HOST 上的服务的端口号，ADDRESS 是一个或多个 IP 地址。

该选项使用用于 host+port 对的条目预先填充 DNS 缓存，因此针对 HOST+PORT 的各种操作都将使用你提供的 ADDRESS 来代替。

比如：

curl --resolve "test.domain:9090:127.0.0.1" http://test.domain:9090/get

4，--limit-rate 用于限制传输速度，模拟慢速网络。比如：

curl --limit-rate 1K :9090/get

上面的命令将传输速度限制到每秒 1KB。

5，与 Cookie 有关的选项

curl 通过 -b、--cookie 选项支持：向服务器发送 Cookie，比如：

curl -b key1=value1 :9090/cookie

上面的命令会生成一个请求头 “Cookie: key1=value1”，向服务器发送一个名称为 key1，值为 value1 的 Cookie。

curl -b key1=value1;key2=value2 :9090/cookie

上面的命令会向服务器发送 2 个 Cookie。

curl -b cookies.txt :9090/cookie

上面的命令从本地文件 cookies.txt 中读取 Cookie，然后将其发送到服务器。

curl 通过 -c、--cookie-jar 选项支持：在操作完成后，将 Cookie 写到文件中，比如：

curl -c cookies.txt :9090/cookie

Cookie 文件的内容类似：

# Netscape HTTP Cookie File# # This file was generated by libcurl! Edit at your own risk.127.0.0.1 FALSE / FALSE key1value1127.0.0.1 FALSE / FALSE key2value2

6，-A 用于指定 User Agent，比如：

curl -A Custom User Agent :9090/user-agent

7，-H、--header 用于自定义请求头，比如：

curl -X POST -d {"key": "value"} -H Content-Type: application/json -H X-Request-Id: id-123 :9090/custom-headers

8，与向服务器发送数据有关的选项

curl 通过 -d、--data 选项支持：向服务器 POST 数据，比如：

curl -d post data :9090/post

curl 通过 --data-urlencode 选项支持：向服务器 POST URL 编码的数据，比如：

curl --data-urlencode post data :9090/post

-d、--data 和 --data-urlencode 选项的值也可以是 “@” + 本地文件名，比如：

curl -d @post.dat :9090/post

上面的命令会读取本地文件 post.dat 的内容，然后将其发送到服务器。

-d、--data 和 --data-urlencode 还可以与 -G、--get 选项结合使用，比如：

curl -G --data-urlencode @post.dat :9090/get

上面的命令会读取本地文件 post.dat 的内容，并自动地对其进行 URL 编码，然后使用 GET 请求将数据发送到服务器。

curl 通过 -T、--upload-file 选项支持：向服务器上传文件，比如：

curl --upload-file put.dat :9090/put

上面的命令会向服务器发送一个 PUT 请求，请求体是本地文件 put.dat 的内容。

curl 通过 -F、--form 选项支持：通过 multipart 的方式向服务器传输数据，比如：

curl --form [email protected] :9090/multipart

上面的命令会加上请求头 Content-Type: multipart/form-data; boundary=<boundary string>，然后将本地文件 multipart.dat 作为 file 字段上传。

-F、--form 选项还支持指定 MIME 和文件名，比如：

curl --form [email protected];type=text/plain;filename=test.txt :9090/multipart

9，-i 用于在输出中包含协议头，比如：

curl -i :9090/get

上面的命令在收到服务器的响应后，首先输出响应头，然后输出空行，最后输出响应体。

10，-I，--head 用于向服务器发送 HEAD 请求，比如：

curl -I :9090/head

11，与重定向有关的选项

curl 默认不跟进重定向，可以通过指定 -L、--location 选项使 curl 跟进重定向，比如：

curl -L :9090/redirect

当指定 -L、--location 选项时，可以通过 --max-redirs 选项指定最大跟进次数，比如：

curl -L --max-redirs 100 :9090/infinitely-redirect

当达到最大跟进次数时，curl 会报类似下面的错误：

curl: (47) Maximum (100) redirects followed

12，与代理服务器有关的选项

curl 通过 -x、--proxy 选项支持：指定将要使用的代理服务器的地址，该选项的值的格式是：

[protocol://]host[:port]

curl 通过 -U、--proxy-user 选项支持：指定代理服务器的账号和密码，该选项的值的格式是：

user:password

13，-u、--user 用于指定服务器的账号和密码，比如：

curl -i -u user:password :9090/basic-auth

上面的命令会加上请求头 Authorization: Basic dXNlcjpwYXNzd29yZA==

14，-v、--verbose 用于调试，curl 将输出通信的整个过程，比如：

curl -v :9090/verbose

15，-o、--output 用于指定：将输出写入到文件，而不是标准输出，比如：

curl -o /dev/null :9090/get

16，-O、--remote-name 用于指定：将输出写入到文件，并将 URL 的最后一部分当作文件名，比如：

curl -O :9090/get

17，-s 和 -S 选项

-s 选项用于开启静默模式，curl 将不输出任何信息；-S 选项和 -s 选项一起使用，使 curl 在发生错误时，输出错误信息。比如：

curl -sS :9090/get

18，-w 选项

curl 的 -w 选项用于在一次完整且成功的操作后输出指定格式的内容到标准输出。输出内容由普通字符串和变量组成，输出变量的格式是 %{variable_name}。curl 会用合适的值替代输出内容中的变量，可用变量如下：

url_effective：最终获取的 URL 地址

http_code：HTTP 状态码

time_total：总时间，单位是秒

time_namelookup：从请求开始到名称解析结束所用的时间，单位是秒

time_connect：从请求开始到TCP连接建立完成所用的时间，单位是秒

time_appconnect：从请求开始到 SSL/SSH 等连接/握手完成所用的时间，单位是秒

time_pretransfer：从请求开始到准备传输所用的时间，单位是秒

time_redirect：重定向时间，单位是秒

time_starttransfer：从请求开始到收到服务器返回的第一个字节所用的时间，单位是秒

size_download：下载大小

size_upload：上传大小

size_header：下载的 header 的大小

size_request：请求的大小

speed_download：平均下载速度，单位是字节/秒

speed_upload：平均上传速度，单位是字节/秒

content_type：被请求的文档的 Content-Type

ssl_verify_result：SSL 验证结果，0 表示成功

比如：

curl -w url effective: %{url_effective}\nhttp code:%{http_code}\ntime total:%{time_total}\ntime namelookup: %{time_namelookup}\ntime connect: %{time_connect}\ntime appconnect: %{time_appconnect}\ntime pretransfer:%{time_pretransfer}\ntime redirect: %{time_redirect}\ntime starttransfer: %{time_starttransfer}\n -Sso /dev/null :9090/get

参考文档

https://curl.se/docs/httpscripting.html

http://www.ruanyifeng.com/blog/2019/09/curl-reference.html