掌握curl：发送JSON格式POST请求的实用技巧

2025-4-13

掌握 curl：发送 JSON 格式 POST 请求的实用技巧

在现代 Web 开发和 API 交互中，JSON (JavaScript Object Notation) 已成为数据交换的事实标准。它轻量、易读、易于机器解析，广泛应用于各种网络服务。而 curl 作为一款强大的命令行工具，用于传输数据，支持多种协议，是开发者、测试人员和系统管理员进行网络请求调试、API 测试和自动化任务不可或缺的利器。

将这两者结合——使用 curl 发送 JSON 格式的 POST 请求——是一项基本但极其重要的技能。POST 请求通常用于向服务器提交数据，例如创建新资源、更新现有数据或执行需要传输数据的操作。当这些数据需要以结构化的 JSON 格式发送时，curl 提供了灵活且强大的方式来实现这一目标。

本文旨在深入探讨使用 curl 发送 JSON POST 请求的各种实用技巧，从基础命令到高级应用，覆盖调试、头部处理、数据来源、脚本集成等多个方面，帮助你全面掌握这一核心技能，提升工作效率。本文预计篇幅较长，内容详实，希望能为你提供一份全面的参考指南。

一、 基础知识回顾：理解核心概念

在深入技巧之前，我们先快速回顾几个核心概念。

  1. curl 是什么？
    curl (Client for URLs) 是一个利用 URL 语法传输数据的命令行工具和库，支持包括 HTTP, HTTPS, FTP, FTPS, SCP, SFTP, TFTP, DICT, TELNET, LDAP 或 FILE 等多种协议。它的功能极其丰富，可以用来发送请求、下载文件、测试 API、进行认证等。其跨平台特性（Linux, macOS, Windows 等）使其应用范围非常广泛。

  2. JSON 是什么？
    JSON 是一种轻量级的数据交换格式，基于 JavaScript 语法的子集。它采用完全独立于语言的文本格式，但也使用了类似于 C 语言家族（包括 C, C++, C#, Java, JavaScript, Perl, Python 等）的习惯，这使得 JSON 成为理想的数据交换语言。其基本结构由键值对（"key": "value"）、数组（[value1, value2]）和嵌套对象/数组构成。

  3. HTTP POST 请求是什么？
    HTTP (HyperText Transfer Protocol) 定义了客户端与服务器之间交互的多种方法（Methods），POST 是其中之一。POST 请求通常用于向指定资源提交数据进行处理。这可能导致在服务器上创建新的资源或更新现有资源。与 GET 请求主要用于获取数据不同，POST 请求体（Request Body）中通常包含需要发送给服务器的数据。

  4. 为何选择 curl 发送 JSON POST 请求？

    • 普遍性与易用性： curl 几乎是所有类 Unix 系统的标配，Windows 上也易于安装。命令行接口直观，学习曲线相对平缓。
    • 灵活性与强大功能： 支持设置请求方法、请求头、请求体、处理 Cookie、进行认证、代理设置等，几乎涵盖了 HTTP 请求的所有方面。
    • 脚本化能力： 作为命令行工具，curl 非常容易集成到 Shell 脚本、CI/CD 流水线或其他自动化流程中，实现 API 自动化测试或数据交互。
    • 调试友好： 提供了详细的输出选项（-v），方便查看请求和响应的完整过程，快速定位问题。

二、 构建基本的 JSON POST 请求

掌握 curl 发送 JSON POST 请求的核心在于理解并正确使用几个关键选项。

  1. 指定请求方法：-X POST
    默认情况下，curl 发送 GET 请求。要发送 POST 请求，需要使用 -X (或 --request) 选项显式指定方法：
    bash
    curl -X POST <URL>

  2. 指定数据内容：-d 或 --data
    这是发送 POST 请求时最重要的选项之一，用于指定要在请求体中发送的数据。对于 JSON 数据，有几种常见的方式提供：

    • 方法一：内联 JSON 字符串
      将 JSON 数据直接作为字符串传递给 -d 选项。注意： JSON 字符串通常需要用单引号 (') 包裹，以避免 Shell 对双引号 (") 和特殊字符（如 $, & 等）进行解释。JSON 内部的字符串必须使用双引号。

      bash
      curl -X POST <URL> \
      -H "Content-Type: application/json" \
      -d '{"username": "testuser", "email": "[email protected]", "isActive": true}'

      • 优点： 简单直接，适用于少量、固定的 JSON 数据。
      • 缺点：
        • 当 JSON 结构复杂或包含特殊字符时，引号嵌套和转义可能变得困难和易错。
        • 不便于复用和维护大量或动态生成的 JSON 数据。
        • 命令行长度有限制，可能不适合非常大的 JSON 载荷。

    • 方法二：从文件读取 JSON 数据 (-d @filename)
      将 JSON 数据保存在一个文件中（例如 data.json），然后使用 -d @ 后跟文件名的方式，让 curl 从该文件中读取数据作为请求体。这是处理复杂或大量 JSON 数据的推荐方式。

      假设 data.json 文件内容如下：
      json
      {
      "productName": "Super Widget",
      "quantity": 100,
      "tags": ["electronics", "new", "gadget"],
      "details": {
      "color": "blue",
      "weight_kg": 0.5
      }
      }

      发送请求的命令：
      bash
      curl -X POST <URL> \
      -H "Content-Type: application/json" \
      -d @data.json

      • 优点：
        • JSON 结构清晰，易于编辑和维护（可以使用 JSON 校验器和格式化工具）。
        • 不受命令行长度限制，可以发送非常大的 JSON 数据。
        • 便于在脚本中动态生成 JSON 文件再发送。
        • 代码更整洁，命令本身更简洁。
      • 缺点： 需要额外管理一个数据文件。

    • 关于 -d vs --data-raw vs --data-binary

      • -d 或 --data: 这是最常用的。当其参数以 @ 开头时，curl 会尝试读取文件内容。它还会默认进行一些 URL 编码处理（虽然对于 Content-Type: application/json 通常不是问题，但了解这点很重要）。
      • --data-raw: 类似于 -d，但它不会对数据进行任何额外的处理或解释（例如，@ 符号会被视为字面量 @ 而不是文件指示符）。如果你想发送包含字面 @ 符号的 JSON 字符串，或者确保数据原样发送，可以使用这个。
      • --data-binary: 与 -d @filename 类似，用于从文件读取数据，但它确保数据以二进制模式读取和发送，并且不会进行任何换行符转换（例如 CRLF 到 LF）。对于纯文本 JSON，通常与 -d @filename 效果相同，但在处理二进制相关场景或需要严格控制换行符时更精确。

      对于发送 JSON 文件，-d @filename 是最常见且通常足够的。

  3. 指定内容类型：-H "Content-Type: application/json" (极其重要！)
    POST 请求发送数据时，必须告知服务器请求体中数据的格式。对于 JSON 数据，标准的 MIME 类型是 application/json。这通过 -H (或 --header) 选项添加一个 Content-Type 请求头来实现。

    ```bash

    结合内联数据

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

    结合文件数据

    curl -X POST \
    -H "Content-Type: application/json" \
    -d @data.json
    ``
    **如果忘记设置这个 Header，服务器可能无法正确解析你发送的 JSON 数据，** 可能会将其视为默认的    application/x-www-form-urlencoded` 格式，导致请求失败或行为异常。

  4. (较新版本 curl) 使用 --json 选项
    较新版本的 curl (7.82.0 及之后) 引入了一个便捷的 --json 选项，它相当于 -X POST -H "Content-Type: application/json" -d <data> 的组合。它可以接受内联 JSON 或 @filename。

    ```bash

    使用内联 JSON

    curl --json '{"key": "value"}'

    使用文件

    curl --json @data.json
    ``
    这个选项大大简化了发送 JSON POST 请求的命令。如果你的    curl版本支持，推荐使用它。可以通过curl --version` 查看版本。

三、 处理请求头 (Headers)

除了 Content-Type，发送 API 请求时经常需要设置其他 Header。

  1. Accept Header：期望服务器返回的格式
    虽然你发送的是 JSON，但你可能期望服务器也返回 JSON 格式的响应。通过 Accept Header 告知服务器你的偏好：
    bash
    curl -X POST <URL> \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @data.json
    服务器不一定会遵循这个请求，但遵循良好实践的 API 通常会。

  2. 认证 (Authentication) Headers
    大多数 API 都需要认证。常见的认证方式通过 Header 实现：

    • Bearer Token (JWT, OAuth2):
      bash
      TOKEN="your_very_long_auth_token_here"
      curl -X POST <URL> \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${TOKEN}" \
      -d @data.json
      (在脚本中使用变量存储 Token 是个好习惯，避免 Token 直接暴露在命令历史中)。

    • Basic Auth:
      虽然可以通过 -u username:password 选项，curl 会自动生成 Authorization: Basic <base64-encoded> Header，但有时你可能想手动设置：
      bash
      # 或者直接使用 -u 选项，更方便
      curl -u "myuser:mypassword" \
      -X POST <URL> \
      -H "Content-Type: application/json" \
      -d @data.json

    • API Keys: 有些 API 使用自定义 Header 传递 API Key：
      bash
      API_KEY="your_api_key"
      curl -X POST <URL> \
      -H "Content-Type: application/json" \
      -H "X-Api-Key: ${API_KEY}" \
      -d @data.json

  3. 添加自定义 Headers
    可以使用多个 -H 选项添加任意数量的自定义 Header：
    bash
    curl -X POST <URL> \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Request-ID: $(uuidgen)" \
    -H "X-Custom-Info: some_value" \
    -d @data.json
    (示例中使用了 uuidgen 命令生成一个唯一的请求 ID)。

四、 调试与响应处理

发送请求后，理解响应和调试问题至关重要。

  1. 查看详细过程：-v 或 --verbose
    这是最重要的调试选项之一。它会打印出详细的交互过程，包括：

    • curl 尝试连接的 IP 地址和端口。
    • TLS/SSL 握手信息（如果使用 HTTPS）。
    • 发送的请求行和所有请求头 (以 > 开头)。 这对于确认 Content-Type, Authorization 等 Header 是否正确设置非常有帮助。
    • 发送的请求体数据 (如果不是非常大)。
    • 服务器返回的状态行和所有响应头 (以 < 开头)。
    • 响应体内容。

    bash
    curl -v -X POST <URL> \
    -H "Content-Type: application/json" \
    -d '{"key": "value"}'
    通过 -v 的输出，你可以精确地看到 curl 发送了什么，服务器响应了什么。

  2. 仅查看响应头：-I 或 --head
    如果你只关心服务器返回的 Header（例如检查 Content-Type, Content-Length, Set-Cookie 等），而不关心响应体，可以使用 -I。注意：-I 会将请求方法改为 HEAD。如果你确实需要发送 POST 请求但只看响应头，结合 -v 并观察输出中的 < 开头的行，或者将响应体丢弃（见下文）。

  3. 抑制输出/仅显示响应体：-s 或 --silent
    默认情况下，curl 会显示进度条和一些信息。-s 可以让 curl 进入静默模式，只输出响应体（如果请求成功且有响应体）。这在脚本中处理响应数据时很有用。

  4. 获取 HTTP 状态码：-w '%{http_code}'
    在脚本中，通常需要检查请求是否成功。HTTP 状态码 (如 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error) 是关键信息。可以使用 -w (或 --write-out) 选项配合特定格式化变量来提取状态码。为了只获取状态码而不显示响应体，通常结合 -s (静默) 和 -o /dev/null (将响应体丢到黑洞)。

    ```bash
    STATUS_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
    -H "Content-Type: application/json" \
    -d @data.json)

    echo "Request finished with status code: ${STATUS_CODE}"

    if [ "${STATUS_CODE}" -eq 201 ]; then
    echo "Resource created successfully."
    elif [ "${STATUS_CODE}" -ge 400 ]; then
    echo "Error occurred. Status code: ${STATUS_CODE}"
    # 可以进一步获取响应体来查看错误详情
    # curl -s -X POST ... > error_response.json
    fi
    ```

  5. 保存响应到文件：-o 或 --output
    将服务器返回的响应体保存到文件中，而不是打印到标准输出。
    ```bash
    curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @data.json \
    -o response.json

    echo "Response saved to response.json"

    可以查看或处理 response.json 文件

    cat response.json
    ```

  6. 美化 JSON 输出 (配合 jq)
    curl 返回的 JSON 响应体通常是压缩的，不易阅读。可以将其通过管道传递给 jq (一个轻量级且强大的命令行 JSON 处理器) 进行格式化和高亮显示。

    bash
    curl -s -X POST <URL> \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @data.json | jq
    如果 jq 未安装，可以使用包管理器安装（如 sudo apt install jq, brew install jq）。jq 不仅能美化，还能查询、过滤和转换 JSON 数据，是处理 curl 响应的绝佳搭档。

五、 进阶技巧与脚本应用

将 curl 用于 JSON POST 请求的能力远不止于此，特别是在脚本化和自动化场景下。

  1. 处理复杂的 JSON 结构
    无论是内联还是文件，curl 对 JSON 结构本身没有限制，只要它是有效的 JSON。对于非常复杂的嵌套对象和数组，使用文件 (-d @filename) 方式几乎是必须的，以保持可读性和可维护性。

  2. 在脚本中使用变量动态生成 JSON
    在自动化脚本中，JSON 数据通常不是静态的，可能需要根据变量动态生成。

    • 使用 printf 或 echo 生成简单 JSON:
      ```bash
      #!/bin/bash
      USERNAME="dynamic_user_$(date +%s)"
      EMAIL="${USERNAME}@test.com"
      JSON_PAYLOAD=$(printf '{"username": "%s", "email": "%s", "isActive": false}' "$USERNAME" "$EMAIL")

      curl -s -X POST \
      -H "Content-Type: application/json" \
      -d "${JSON_PAYLOAD}" \
      -o response.json
      ```
      注意：这种方法对于包含特殊字符的变量值需要仔细处理转义，容易出错。

    • 使用 jq 生成 JSON (更健壮的方式):
      jq 可以安全地处理变量并生成合法的 JSON。
      ```bash
      #!/bin/bash
      USERNAME="dynamic_user_$(date +%s)"
      EMAIL="${USERNAME}@test.com"
      TAGS=("beta" "test" "scripted") # Bash array

      Use jq to build the JSON payload

      --arg binds a string variable, --argjson binds a JSON value (like bool or number), --arg A B reads array A from shell variable B

      JSON_PAYLOAD=$(jq -n \
      --arg user "$USERNAME" \
      --arg mail "$EMAIL" \
      --argjson active false \
      --argjson tags "$(printf '%s\n' "${TAGS[@]}" | jq -R . | jq -s .)" \
      '{username: $user, email: $mail, isActive: $active, tags: $tags}')

      echo "Generated JSON payload:"
      echo "${JSON_PAYLOAD}" | jq # Pretty print for verification

      curl -s -X POST \
      -H "Content-Type: application/json" \
      -d "${JSON_PAYLOAD}" \
      -o response.json

      Check status code (as shown before)

      ...

      ```
      这种方法更安全，不易因特殊字符导致 JSON 无效。

    • 生成 JSON 文件再发送:
      对于非常复杂的动态 JSON，可以先用脚本（Python, Node.js, PHP, or even advanced jq）生成一个临时的 .json 文件，然后使用 curl -d @temp_data.json 发送。
      ```bash
      #!/bin/bash
      # Assume a script generate_payload.py creates data.json based on inputs
      python generate_payload.py --user "some_user" --value 123

      if [ -f data.json ]; then
      curl -X POST \
      -H "Content-Type: application/json" \
      -d @data.json \
      -o response.json
      rm data.json # Clean up temporary file
      else
      echo "Failed to generate data.json"
      exit 1
      fi
      ```

  3. 错误处理与重试
    在脚本中，检查 HTTP 状态码是基本的错误处理。对于网络波动或临时服务端错误 (如 502, 503, 504)，可能需要实现重试逻辑。
    ```bash
    #!/bin/bash
    MAX_RETRIES=3
    RETRY_DELAY=5 # seconds
    URL=""
    JSON_FILE="data.json"

    for ((i=1; i<=MAX_RETRIES; i++)); do
    STATUS_CODE=$(curl -s -o response.tmp -w "%{http_code}" -X POST "$URL" \
    -H "Content-Type: application/json" \
    -d @"$JSON_FILE")

    echo "Attempt $i: Status Code = $STATUS_CODE"

if [ "$STATUS_CODE" -ge 200 ] && [ "$STATUS_CODE" -lt 300 ]; then
    echo "Success!"
    mv response.tmp final_response.json
    # Process final_response.json if needed
    exit 0
elif [ "$STATUS_CODE" -ge 500 ]; then
    echo "Server error encountered. Retrying in ${RETRY_DELAY}s..."
    sleep "$RETRY_DELAY"
else
    # Handle other errors (4xx client errors usually shouldn't be retried)
    echo "Client error or unexpected status: $STATUS_CODE. Aborting."
    cat response.tmp # Show error response body
    rm response.tmp
    exit 1
fi

    done

    echo "Max retries reached. Request failed."
    rm response.tmp
    exit 1
    ```

  4. 安全注意事项

    • 避免在命令行中直接包含敏感信息： 如密码、Token、API Keys。这些会记录在 Shell 历史中。
    • 使用环境变量： 将敏感信息存储在环境变量中，脚本中引用 (e.g., -H "Authorization: Bearer $MY_API_TOKEN")。
    • 从文件读取： 将 Token 或凭证存储在受保护的文件中，脚本读取后再使用。curl 也支持从文件读取某些选项的值 (e.g., -d @file, --config file)。
    • 使用 curl 的 --config 文件： 可以将常用的选项（包括 Header 和 URL）保存在一个配置文件中，通过 curl -K myconfig.txt 或 curl --config myconfig.txt 加载。
    • 注意 HTTPS： 始终优先使用 HTTPS (https://) URL 来加密传输过程中的数据。curl 默认会验证服务器证书。如果需要跳过验证（不推荐，除非在受信任的内部环境或测试中），可以使用 -k 或 --insecure。

六、 实际应用场景

掌握 curl 发送 JSON POST 请求的技巧，可以在多种场景下发挥巨大作用：

  1. API 测试：

    • 手动测试：快速验证 API 端点是否按预期工作，发送特定数据看响应。
    • 自动化测试：集成到测试框架或脚本中，对 API 进行回归测试、集成测试。

  2. 自动化脚本：

    • 数据同步：定期将一个系统的数据通过 API 发送到另一个系统。
    • 任务触发：通过调用 API 触发服务器上的某个任务或流程。
    • DevOps/CI/CD：在部署流程中调用 API 更新配置、通知状态、触发构建等。

  3. 快速原型验证：
    在没有完整客户端应用的情况下，用 curl 模拟客户端行为，与正在开发的后端 API 进行交互。

  4. Webhooks 测试：
    模拟外部服务向你的 Webhook URL 发送 JSON POST 请求，测试你的接收端逻辑。

七、 总结

curl 是一个极其强大且灵活的工具，而发送 JSON POST 请求是其在现代 Web 环境中最常见的用途之一。掌握这项技能，需要理解 POST 方法的意义、JSON 数据的结构，以及 curl 提供的关键选项：

  • -X POST 指定方法。
  • -H "Content-Type: application/json" 声明数据格式 (至关重要)。
  • -d '...' 或 -d @filename (推荐) 提供 JSON 数据。
  • (新版本) --json 提供便捷语法。
  • -H 添加其他必要的 Header (如 Accept, Authorization)。
  • -v 用于详细调试。
  • -s, -o, -w '%{http_code}' 用于脚本化处理和响应控制。
  • 配合 jq 可以更好地处理和查看 JSON 响应。

通过熟练运用这些技巧，结合脚本化能力和对安全性的关注，你可以高效地与任何提供 JSON API 的服务进行交互，无论是进行测试、开发、调试还是自动化任务。curl 的世界远不止于此，但精通 JSON POST 请求无疑是其中最实用、最核心的一环。希望这篇详尽的指南能助你成为 curl 使用的高手！

版权声明：
作者：admin
链接：https://hostlocvps.com/2025/04/13/%e6%8e%8c%e6%8f%a1curl%ef%bc%9a%e5%8f%91%e9%80%81json%e6%a0%bc%e5%bc%8fpost%e8%af%b7%e6%b1%82%e7%9a%84%e5%ae%9e%e7%94%a8%e6%8a%80%e5%b7%a7/
文章版权归作者所有，未经允许请勿转载。
THE END
UDP协议是什么？一文读懂其原理与应用
<<上一篇
深入理解CSS-in-JS：原理、优势与最佳实践
下一篇>>
相关推荐
```
探索Steam Deck的无限可能
探索SQLite：关系数据库的力量
Steam Deck OLED 购买指南
如何将 55 华氏度转换为摄氏度
免费下载 IntelliJ IDEA 社区版
探索GitHub上的Clash for Windows生态系统
Java 24 常见问题解答 (FAQ)
Z-Library：最新网址和访问解决方案
Azure TTS：让你的应用“声”动人心