常用curl参数及样例讲解

1 缘起

后端/后台项目开发过程中，有两个阶段的接口测试和验证，自测阶段，通过Postman构建请求，
自建一些参数，测试功能以及边界条件，这些都是可以自行掌控的，当完成功能验证与前端对接时，
前端会根据接口文档进行调试，当请求接口遇到问题时，需要和后端进行验证，前端在浏览器端获取到的完整接口请求即curl提供给后端/后台开发人员，后端/后台开发人员可以直接使用curl进行接口验证，无需重新将curl转为Postman中的请求，当然，Postman提供了curl转成请求的功能，方便持久化。在使用curl的过程中，发现有些参数还是没有很清晰是做什么的，于是，抽时间整理了一下常用请求对应的curl参数，分享如下，帮助提高开发效率。
虽然curl可以直接通过浏览器提供，但是，自行构建时，仍需熟悉相关参数才能快速构建，
当然，Postman也可以直接根据构建的请求生成curl，本文旨在补充知识。

2 curl

图片来源：https://curl.se/

curl是通过URL传输数据的命令行工具和库。支持的协议有：HTTP、HTTPS、FTP、FTPS、TELNET和TFPT等等。
用户通过终端执行curl命令与远程服务器交换数据，同时，curl支持文件上传、断点续传和代理等高级功能。

官网：https://curl.se/
参数：https://curl.se/docs/manpage.html

2.1 常用参数

这里列出了最常用的请求方式所使用的curl参数，包括：

• 请求头
• 表单
• 请求体：JSON/x-www-form-urlencoded

参数简要描述及样例见下表：

序号	参数	缩写	简要描述
1	--location	-L	用于重新请求URL，当配置的URL定向到其他地址时，会重新发送请求到新的URL
2	--header	-H	配置请求头参数，如--header 'm-header-name: m-value'
3	--basic	无	配置Basic认证参数，结合user参数，当然，配置Basic认证也可以直接使用请求头的方式，如--header 'Authorization: Basic value'
4	--user	-u	配置用户认证信息，结合Basic使用，如--basic --user username:password
5	--oauth2-bearer	无	配置Bearer认证，如--oauth2-bearer 'token-value'，同样可以直接使用请求头方式，如--header 'Authorization: Bearer value'
6	--form	-F	配置表单数据
7	--data	-d	配置请求体为JSON的数据
8	--data-urlencode	无	配置请求体为x-www-form-urlencoded格式的数据

2.2 测试样例

2.2.1 请求头：header

2.2.1.1 普通header参数

普通header参数直接使用--header参数，数据格式为key: value，样例如下：

curl --location 'http://localhost:9121/api/v1/common/header' \
--header 'token: token-token'

测试结果如下：

2.2.1.2 Basic认证header参数

Basic认证使用header参数时，固定的key为Authorization，值为Basic配合用户名和密码加密后的数据，
固定格式：--header 'Authoriztion: Basic value'，样例如下：

curl --location 'http://localhost:9121/api/v1/common/auth' \
--header 'Authorization: Basic eGlhb2h1YToxMjM0NTY='

测试结果如下：

2.2.1.3 Bearer认证header参数

Bearer认证参数固定键为Authorization，值为Bearer拼装Token，
固定格式为：--header 'Authorization: Bearer value'，样例如下：

curl --location 'http://localhost:9121/api/v1/common/auth' \
--header 'Authorization: Bearer NjMyZDc3YTBlZTliYjBlNDI3YTU1OWJhOmR5eHA2MmotblB2aWZubExTY3dVUUVZVmlhWEQ3bGJo'

测试结果如下：

2.2.2 Basic认证参数

Basic认证参数直接使用时需要结合user参数，显式地使用用户名和密码。
固定格式为：--basic --user username:password，样例如下：

curl --location 'http://localhost:9121/api/v1/common/auth' \
--basic --user xiaohua:123456

测试结果如下：

2.2.3 Bearer认证参数

Bearer认证参数直接使用固定格式为：
--oauth2-bearer 'value'，样例如下：

curl --location 'http://localhost:9121/api/v1/common/auth' \
--oauth2-bearer 'NjMyZDc3YTBlZTliYjBlNDI3YTU1OWJhOmR5eHA2MmotblB2aWZubExTY3dVUUVZVmlhWEQ3bGJo'

测试结果如下：

2.2.4 Path参数

Path参数即数据直接作为URL的一部分，没有特别的参数，直接使用URL即可，
这里使用--location仅是为了保证URL重定向后可以重新请求URL，无特别说明可以不使用该参数，
固定的格式直接在curl后面添加完整URL，固定格式：curl URL，样例如下：

curl --location 'http://localhost:9121/api/v1/common/path/123456'

测试结果如下：

2.2.5 Params参数

在URL中拼接参数时，和Path参数一样，只需提供完整的URL，
固定格式：curl URL，样例如下：

curl --location 'http://localhost:9121/api/v1/common/params?token=token-token&username=user-name'

测试结果如下：

2.2.6 Body参数

请求体参数常用的三种形式：表单/JSON/x-www-form-urlencoded。

2.2.6.1 form-data

表单数据分为普通的键值对，和文件传输表单。

• 键值对form-data数据
  键值对的表单固定格式为：--form 'key-name="value"'，样例如下：

curl --location 'http://localhost:9121/api/v1/common/form-data' \
--form 'token="token-token"' \
--form 'username="user-name"'

测试结果如下：

• file form-data数据
  文件表单数据参数有些不同，需要添加固定的数据@，固定格式：
  --form 'key=@file-path'，样例如下：

curl --location 'http://localhost:9121/api/v1/common/form-data/file' \
--form 'file=@D:/workfile/snapshot/写作-1.png'

测试结果如下：

curl --location 'http://localhost:9121/api/v1/common/form-data/file' \
--form 'file=@"D:/workfile/snapshot/写作-1.png"'

注意：这里的文件路径拼装有两种方式，添加双引号和不添加双引号，无比根据自己的操作系统确定是否添加。
有一次使用Linux服务器，自动化部署服务时，调用Azkaban接口，上传文件，使用了双引号，上传失败，后来是同事发现了这个，去除双引号才上传成功

2.2.6.2 JSON

JSON格式的请求体数据，固定格式为：--data 'JSON数据'，样例如下：

curl --location 'http://localhost:9121/api/v1/common/json' \
--header 'Content-Type: application/json' \
--data '{
    "token":"token-token",
    "username":"user-name"
}'

测试结果如下：

2.2.6.3 x-www-form-urlencoded

x-www-form-urlencoded格式的请求体需要使用的参数为data-urlencode，
固定格式为：--data-urlencode 'key=value'，样例如下：

curl --location 'http://localhost:9121/api/v1/common/x-www-form-urlencoded' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=token-token' \
--data-urlencode 'username=user-name'

测试结果如下：

3 小结

（1）curl是传输数据的命令行工具；
（2）curl请求HTTP/HTTPS接口时常用的参数：--header/--form/--data/--data-urlencode/--basic/--user/--oauth2-bearer，分别对应：请求头/表单/JSON请求体/x-www-form-urlencoded请求体/Basic认证/Bearer认证；
（3）curl常用于前后端接口验证，无需重新构建请求（如Postman构建），直接使用curl即可。