概述

前几天在微信群与“知名”技术博客芋道源码的作者芋艿同学讨论了一个问题:通过哪些方式可以方便地测试 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 请求报文的格式如下:

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

其中 CRLF 代表回车(CR,即 '\r')加换行(LF,即 '\n')。

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

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

User-Agent: curl/7.59.0

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

http-request.jpg

注:图片转载自:https://www.cnblogs.com/lmh001/p/9928517.html


HTTP/1.X 请求的流程

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


curl 的常用选项

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

1,-X 用于指定请求方法,比如:

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

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

curl -0 http://127.0.0.1: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 http://127.0.0.1:9090/get

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

5,与 Cookie 有关的选项

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

curl -b 'key1=value1' http://127.0.0.1:9090/cookie

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

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

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

curl -b cookies.txt http://127.0.0.1:9090/cookie

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

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

curl -c cookies.txt http://127.0.0.1:9090/cookie

Cookie 文件的内容类似:

# Netscape HTTP Cookie File
# http://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.
127.0.0.1       FALSE   /       FALSE   1609147946      key1    value1
127.0.0.1       FALSE   /       FALSE   1609147946      key2    value2

6,-A 用于指定 User Agent,比如:

curl -A 'Custom User Agent' http://127.0.0.1:9090/user-agent

7,-H、--header 用于自定义请求头,比如:

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

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

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

curl -d 'post data' http://127.0.0.1:9090/post

 

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

curl --data-urlencode 'post data' http://127.0.0.1:9090/post

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

curl -d @post.dat http://127.0.0.1:9090/post

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

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

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

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

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

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

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

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

curl --form 'file=@multipart.dat' http://127.0.0.1:9090/multipart

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

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

curl --form 'file=@multipart.dat;type=text/plain;filename=test.txt' http://127.0.0.1:9090/multipart

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

curl -i http://127.0.0.1:9090/get

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

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

curl -I http://127.0.0.1:9090/head

11,与重定向有关的选项

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

curl -L http://127.0.0.1:9090/redirect

 

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

curl -L --max-redirs 100 http://127.0.0.1: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' http://127.0.0.1:9090/basic-auth

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

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

curl -v http://127.0.0.1:9090/verbose

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

curl -o /dev/null http://127.0.0.1:9090/get

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

curl -O http://127.0.0.1:9090/get

17,-s 和 -S 选项

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

curl -sS http://127.0.0.1:9090/get

18,-w 选项

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

比如:

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 http://127.0.0.1:9090/get

19,与超时有关的选项

--connect-timeout 选项用于指定建立连接的超时时间,单位是秒,比如:

curl --connect-timeout 1 http://127.0.0.1:9090/get

-m、--max-time 选项用于指定最长传输时间,单位是秒,比如:

curl -m 2 http://127.0.0.1:9090/sleep/1

当传输时间达到该限制时,如果传输仍然没有结束,那么 curl 将以类似下面的错误退出:

curl: (28) Operation timed out after 2001 milliseconds with 34 out of -1 bytes received

参考文档