curl_setopt POST参数如何正确设置？

CURLOPT_POST 是 libcurl 库中的一个核心选项，它的作用是告诉 cURL 库：“接下来的请求要使用 HTTP POST 方法来发送，而不是默认的 GET 方法”。

当你设置 CURLOPT_POST 为 1 (或 true) 时，cURL 会自动做以下几件事：

1. 将请求方法从 GET 改为 POST。
2. 设置 Content-Type 请求头为 application/x-www-form-urlencoded（这是最常见的形式）。
3. 在 HTTP 请求中添加一个 Content-Length 请求头，用于告知服务器请求体的大小。

CURLOPT_POST 的基本用法

在使用 CURLOPT_POST 时，你通常还需要配合其他几个选项来完整地构建一个 POST 请求。

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

这是最常见的 POST 请求类型，通常用于提交普通的 HTML 表单。

关键选项组合：

• CURLOPT_POST: 设置为 1，启用 POST 方法。
• CURLOPT_POSTFIELDS: 设置为要发送的数据，可以是一个字符串，也可以是一个关联数组（在 PHP 7.1.2 之后）。

示例代码 (PHP):

<?php
// 初始化 cURL 会话
$ch = curl_init();
// 设置要请求的 URL
curl_setopt($ch, CURLOPT_URL, "https://example.com/api/submit");
// 启用 POST 方法
curl_setopt($ch, CURLOPT_POST, 1);
// 设置要 POST 发送的数据
// 方式一：直接使用字符串 (key1=value1&key2=value2)
// $post_data = "username=john.doe&password=secret123";
// curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
// 方式二：使用关联数组（cURL 会自动将其转换为 URL 编码的字符串，并设置正确的 Content-Type）
$post_data = [
    'username' => 'john.doe',
    'password' => 'secret123',
    'email'    => 'john.doe@example.com'
];
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
// (可选) 如果你不想让 cURL 自动设置 Content-Type，可以手动覆盖
// curl_setopt($ch, CURLOPT_HTTPHEADER, [
//     'Content-Type: application/x-www-form-urlencoded'
// ]);
// 设置为 TRUE，将获取的信息以字符串返回，而不是直接输出
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// 执行 cURL 会话
$response = curl_exec($ch);
// 检查是否有错误发生
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
// 关闭 cURL 会话
curl_close($ch);
// 输出响应
echo $response;
?>

发送 JSON 数据

在现代 Web API 开发中，发送 JSON 数据是非常普遍的，这时，CURLOPT_POST 仍然需要设置，但 CURLOPT_POSTFIELDS 的内容和 Content-Type 请求头需要手动指定。

关键选项组合：

• CURLOPT_POST: 设置为 1。
• CURLOPT_POSTFIELDS: 设置为 JSON 格式的字符串。
• CURLOPT_HTTPHEADER: 手动设置 Content-Type: application/json 请求头。

示例代码 (PHP):

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://example.com/api/users");
curl_setopt($ch, CURLOPT_POST, 1);
// 准备要发送的 JSON 数据
$data_to_send = [
    'name'  => 'Jane Doe',
    'job'   => 'Software Engineer'
];
$json_data = json_encode($data_to_send);
// 设置 POST 数据为 JSON 字符串
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);
// 手动设置 Content-Type 为 application/json
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($json_data) // 虽然 cURL 通常会自动计算，但手动设置更明确
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
echo $response;
?>

CURLOPT_POST 与 CURLOPT_CUSTOMREQUEST 的区别

你可能需要发送一个 PUT、DELETE 或其他自定义的 HTTP 方法，这时，CURLOPT_POST 就不适用了。

• CURLOPT_POST: 专门用于 POST 请求，它会自动处理 Content-Type 和 Content-Length 等与 POST 相关的细节。
• CURLOPT_CUSTOMREQUEST: 用于设置一个自定义的 HTTP 请求方法，如 PUT, DELETE, PATCH 等。

重要提示: 当你使用 CURLOPT_CUSTOMREQUEST 时，cURL 不会 自动添加 Content-Length 请求头，如果你的请求体不为空，你必须手动添加 Content-Length 请求头，否则服务器可能无法正确处理你的请求。

示例代码 (发送 PUT 请求):

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://example.com/api/users/123");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT"); // 设置自定义方法为 PUT
$data_to_send = json_encode(['name' => 'Updated Name']);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_to_send);
// 必须手动设置 Content-Type 和 Content-Length
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_to_send)
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
// ... 错误检查和关闭 ...
echo $response;
?>

总结表格

最佳实践

1. 发送表单数据: 使用 CURLOPT_POST + 关联数组形式的 CURLOPT_POSTFIELDS，这是最简单、最不容易出错的方式。
2. 发送 JSON 数据: 使用 CURLOPT_POST + CURLOPT_POSTFIELDS (JSON 字符串) + CURLOPT_HTTPHEADER (设置 Content-Type: application/json)。
3. 发送非 POST 方法 (如 PUT/DELETE): 使用 CURLOPT_CUSTOMREQUEST + CURLOPT_POSTFIELDS + 必须手动设置 Content-Length。
4. 始终检查错误: 使用 curl_errno() 和 curl_error() 来捕获 cURL 执行过程中可能发生的网络或协议错误。