POST 请求通常用于向服务器提交数据，例如提交表单、上传文件或创建新的资源。

最基本的 POST 请求

最基本的 POST 请求不带任何数据,只发送一个请求行。

curl -X POST http://example.com/api/resource

• -X POST: 指定 HTTP 请求方法为 POST，虽然 curl 在没有 -X 且没有 -d（数据）选项时，默认也会使用 POST，但显式声明是一个好习惯,能让命令意图更清晰。

发送表单数据（application/x-www-form-urlencoded）

这是最常见的 POST 请求场景之一，比如模拟网页表单提交，使用 -d 或 --data 选项。

示例 1：发送单个键值对

curl -X POST -d "name=John&age=30" http://example.com/api/users

• -d "name=John&age=30": 指定了要发送的数据。curl 会自动将 Content-Type 设置为 application/x-www-form-urlencoded。

示例 2：从文件读取数据

如果你的表单数据量很大，或者需要复用，可以将其保存在一个文件中，然后让 curl 读取。

创建一个数据文件 data.txt：

username=admin
password=secret123

执行命令：

curl -X POST -d @data.txt http://example.com/api/login

• -d @data.txt: 符号告诉 curl 从后面的文件中读取数据作为请求体。

示例 3：自动设置 Content-Type

当你使用 -d 发送数据时，curl 会自动设置 Content-Type 头,你也可以手动覆盖它：

curl -X POST -d "some data" -H "Content-Type: application/x-www-form-urlencoded" http://example.com/api

发送 JSON 数据（application/json）

在开发 API 时，发送 JSON 数据是标准做法，这里的关键是手动设置 Content-Type 头。

示例 1：直接发送 JSON 字符串

curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "Jane", "email": "jane@example.com"}' \
http://example.com/api/users

• -H "Content-Type: application/json": 至关重要，这告诉服务器你发送的是 JSON 格式的数据。
• -d '{...}': JSON 字符串通常需要用单引号 括起来，以防止 shell 对其中的双引号 进行解释。

示例 2：从 JSON 文件读取数据（推荐）

这是最常用和最清晰的方式。

创建一个 JSON 文件 user.json：

{
  "name": "Peter",
  "email": "peter@example.com",
  "is_active": true
}

执行命令：

curl -X POST \
-H "Content-Type: application/json" \
-d @user.json \
http://example.com/api/users

• -d @user.json: 从 user.json 文件中读取数据并发送。

发送文件上传（multipart/form-data）

当需要上传文件时，必须使用 multipart/form-data 编码。curl 提供了 -F 或 --form 选项来处理这个场景。

-F 选项会自动设置 Content-Type 为 multipart/form-data,并正确处理文件和普通字段的边界。

示例：上传文件并附带其他表单字段

假设我们要上传一个名为 report.pdf 的文件，并附带一个 description 字段。

curl -X POST \
-F "file=@report.pdf" \
-F "description=Quarterly financial report" \
http://example.com/api/upload

• -F "file=@report.pdf": file= 是表单字段的名称，@report.pdf 表示上传当前目录下的 report.pdf 文件。
• -F "description=...": 可以同时添加多个普通文本字段。

添加 HTTP 请求头

使用 -H 或 --header 选项可以添加自定义的 HTTP 请求头，这在需要传递认证信息（如 Authorization）或自定义头时非常有用。

示例：添加 Authorization 头

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"user_id": 123}' \
http://example.com/api/protected-resource

处理响应

默认情况下，curl 会将服务器的响应（包括 HTTP 头和响应体）输出到标准输出（通常是你的终端）。

示例 1：只显示响应体

使用 -s 或 --silent 选项可以隐藏进度表和错误信息,使输出更干净。

curl -s -X POST -d '{"key":"value"}' http://example.com/api | jq .

• | jq .: 如果响应是 JSON，可以将其通过管道传给 jq 工具进行格式化输出,非常方便。

示例 2：将响应保存到文件

使用 -o 或 --output 选项可以将响应体保存到文件。

curl -o response.json -X POST -d '{"key":"value"}' http://example.com/api

• -o response.json: 将响应体保存到 response.json 文件中。

示例 3：显示 HTTP 状态码

使用 -w 或 --write-out 选项可以自定义输出格式，例如只显示 HTTP 状态码。

# -o /dev/null 表示不输出响应体，-w 表示自定义输出
curl -o /dev/null -w "%{http_code}\n" -X POST -d '{"key":"value"}' http://example.com/api

• -o /dev/null: 将响应体丢弃,不显示在终端。
• -w "%{http_code}\n": 输出 HTTP 状态码（如 200, 201, 404, 500）,并在后面换行。
• 常用的 变量：
  • %{http_code}: HTTP 状态码
  • %{time_total}: 总传输时间
  • %{size_download}: 下载的总字节数

综合实例：一个完整的 POST 请求

假设我们要调用一个 RESTful API 来创建一个用户，这个 API 需要：

1. POST 方法。
2. Content-Type: application/json。
3. Authorization: Bearer <token>。
4. 一个 JSON 请求体。

命令如下：

# 1. 设置变量，方便修改
API_URL="https://api.example.com/v1/users"
API_TOKEN="your_secret_api_token_here"
USER_DATA='{"username": "newuser", "email": "newuser@example.com", "role": "user"}'
# 2. 执行 curl 命令
curl -s \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${API_TOKEN}" \
-d "${USER_DATA}" \
"${API_URL}" | jq .

命令分解：

• curl -s: 静默模式,不显示进度条。
• -X POST: 指定 POST 方法。
• -H "Content-Type: application/json": 设置内容类型。
• -H "Authorization: Bearer ${API_TOKEN}": 设置认证头。
• -d "${USER_DATA}": 发送 JSON 数据。
• "${API_URL}": 目标 URL。
• | jq .: 将 JSON 响应通过 jq 工具进行美化输出。

希望这份详细的指南能帮助你熟练掌握 curl 的 POST 请求用法！