cURL POST 请求：JSON、表单和文件上传

发送 cURL POST 请求前，选择端点支持的正文格式。--json 使用适当的默认请求头发送 JSON，--data-urlencode 编码表单值，--form 创建 multipart 上传。正文选项已经选择 POST 时，通常无需再添加 -X POST。

示例使用本地回显服务器展示实际接收内容。通过 python3 demo_server.py 启动附带服务，再运行以下命令。示例使用 Bash 语法；Windows 请调用 curl.exe，并按所用 Shell 调整引号。

1. 使用 cURL POST 发送 JSON

curl --fail-with-body -sS --max-time 30 \
  --json '{"category":"office","limit":3}' \
  'http://127.0.0.1:8766/echo'

接收端会报告 method: POST、JSON 内容类型，以及 json 字段中的对象。未被覆盖时，--json 添加 JSON Content-Type 和 Accept，但发送前不会验证任意文本是否为有效 JSON。

使用 curl --version 检查安装版本。--json 从 cURL 7.82.0 起可用；旧版本应显式发送正文和请求头：

curl --fail-with-body -sS --max-time 30 \
  -H 'Content-Type: application/json' \
  --data-binary '{"category":"office","limit":3}' \
  'http://127.0.0.1:8766/echo'

当前 cURL 手册列出了这些选项。本地服务器会校验 JSON，因此格式错误会产生可检查的 400 响应。

2. 发送表单时保留特殊字符

curl --fail-with-body -sS --max-time 30 \
  --data-urlencode 'category=office' \
  --data-urlencode 'query=desk & lamp' \
  'http://127.0.0.1:8766/echo'

回显的查询值为 desk & lamp。编码防止值内的 & 被解释成另一个表单字段的分隔符。

明确提供已构造的表单正文时，可使用 -d 'a=1&b=2'，但它不会自动编码值中的每个字符。应按数据需求选择编码方式，而非只选择看起来较短的命令。

3. 发送 JSON 文件或 multipart 上传

将以下虚构对象保存为 payload.json：

{"category":"office","limit":3}

作为请求体发送：

curl --fail-with-body -sS --max-time 30 \
  --json @payload.json \
  'http://127.0.0.1:8766/echo'

对于文件上传端点，创建 sample.csv，改用 multipart 语法：

curl --fail-with-body -sS --max-time 30 \
  --form 'source=tutorial' \
  --form 'file=@sample.csv;type=text/csv' \
  'http://127.0.0.1:8766/echo'

这是不同类型的请求。JSON 文件输入将文件内容作为 JSON 正文发送；multipart 上传将文件作为有名称的独立部分，与其他部分一起发送。让 cURL 构造 boundary，不要强制设置不完整的 Content-Type。

4. 选择能够保留预期字节的选项

除非手册明确说明支持，否则不要在同一命令中混合正文模式。-X POST 只改变方法字符串，不会把错误编码的正文变成有效 JSON 或 multipart。

5. 分别保存正文与状态

curl --fail-with-body -sS --max-time 30 \
  --json '{"category":"office","limit":3}' \
  --dump-header response-headers.txt \
  --output response.json \
  --write-out 'HTTP %{http_code}\n' \
  'http://127.0.0.1:8766/echo'

正文写入 response.json，响应头写入独立文件，状态码显示在终端。--fail-with-body 使 HTTP 错误返回失败，同时保留正文供检查。除了 HTTP 状态码，还应检查命令退出码；网络故障可能没有可用的 HTTP 响应。

详细日志可能暴露鉴权请求头。请使用示例凭据，不要分享包含私密值的原始日志。

6. 检查重定向和重试行为

添加 --location 会改变流程。重定向后的方法取决于响应状态及所用选项。不要把 -X POST 当作通用修复，因为它强制方法字符串的方式可能不同于普通正文处理。

创建任务的操作超时后，结果可能不确定。重新发送创建请求前，检查任务查询或调用日志。MIYAIP Crawler API 指南区分了任务提交和任务获取。

需要把可用请求转成 Python 时，可使用转换器支持的内联选项。文件上传及复杂重定向组合需要手动检查，不应静默转换。

先用一个小请求确认方法、正文格式与响应，再应用真实服务的鉴权、参数及任务生命周期。