Python post请求常见问题：如何正确传递JSON参数？

Question

在使用 Python 发送 POST 请求时，一个常见问题是：**如何正确传递 JSON 参数？** 许多开发者在使用 `requests` 库时，不清楚应使用 `json` 参数还是 `data` 参数来发送 JSON 数据。若直接传递字典给 `data`，可能造成数据未被正确序列化或请求头未设置为 `application/json`，从而导致服务器拒绝请求。 正确的做法是使用 `requests.post()` 中的 `json` 参数，它会自动将字典序列化为 JSON 字符串，并设置合适的 Content-Type 请求头。理解这一区别能有效避免 400、415 等常见错误。

Answer 1

一、问题背景：POST 请求中的 JSON 参数传递

在使用 Python 的 requests 库发送 POST 请求时，开发者常遇到的一个问题是：如何正确地将数据以 JSON 格式传递给服务器？常见的疑惑在于应使用 json 参数还是 data 参数。

很多初学者会直接将字典对象传入 data 参数中，例如：

import requests

response = requests.post(
    'https://api.example.com/data',
    data={'key': 'value'}
)

然而，这种方式并不会自动将字典转换为 JSON 字符串，也不会设置正确的 Content-Type: application/json 请求头。这可能导致服务器返回 400（Bad Request）或 415（Unsupported Media Type）等错误。

二、原理分析：json vs data 参数的区别

参数类型	是否自动序列化	是否设置 Content-Type	适用场景
json	是	是（application/json）	发送 JSON 数据
data	否	否	发送表单数据或原始字符串

从上表可以看出，json 参数更适合用于发送结构化的 JSON 数据。它不仅会自动调用 json.dumps() 进行序列化，还会在请求头中添加 Content-Type: application/json，从而确保服务端能够正确解析接收到的数据。

三、解决方案与最佳实践

推荐做法是使用 json 参数来传递 JSON 数据。示例代码如下：

import requests

response = requests.post(
    'https://api.example.com/data',
    json={'key': 'value'}  # 自动序列化并设置 Content-Type
)

如果你希望手动控制 JSON 序列化过程，也可以使用 data 参数，但需要显式地进行序列化，并设置请求头：

import requests
import json

response = requests.post(
    'https://api.example.com/data',
    data=json.dumps({'key': 'value'}),
    headers={'Content-Type': 'application/json'}
)

四、深入理解：HTTP 协议与内容协商

当客户端向服务器发送请求时，通常通过请求头中的 Content-Type 来告知服务器所发送的内容类型。服务器根据该字段决定如何解析请求体。

若未设置正确的 Content-Type，服务器可能尝试以默认方式解析数据（如表单格式），从而导致解析失败。

此外，某些 API 接口会对 Accept 头进行检查，要求客户端声明期望的响应格式。因此，在构建健壮的 HTTP 客户端时，建议同时设置以下头部信息：

• Content-Type: application/json
• Accept: application/json

五、流程图：JSON 请求发送逻辑

graph TD
    A[开始] --> B{使用 json 参数?}
    B -- 是 --> C[自动序列化数据]
    B -- 否 --> D[需手动序列化]
    C --> E[设置 Content-Type: application/json]
    D --> F[设置 headers['Content-Type']]
    E --> G[发送请求]
    F --> G