本文深入探讨了将python中处理json数据的POST请求转换为php时常遇到的陷阱。核心问题在于Python的requests.post(data=…)会将数据表单编码，即使其中包含JSON字符串；而PHP中若直接将整个请求体json_encode会导致API拒绝。教程将详细解释如何正确地在PHP中构建请求，确保只有特定参数的值被JSON编码，从而成功调用FedEx等API。
在进行跨语言的api调用代码转换时，一个常见的挑战是理解不同语言或库处理http请求体的方式差异。尤其是在处理包含json数据的post请求时，python的requests库和php的http客户端库（如requests或cURL）之间存在微妙但关键的区别。本文将以fedex追踪api为例，详细阐述这种差异及其解决方案。
Python requests库的POST请求机制分析
原始的python脚本使用requests.post()方法向FedEx追踪API发送请求。关键在于其data参数的构造方式：
data = requests.post('https://www.fedex.com/trackingCal/track', data={ 'data': json.dumps({ # 注意这里，'data'的值被json.dumps处理 'TrackPackagesRequest': { # ... } }), 'action': 'trackpackages', 'locale': 'en_US', 'format': 'json', 'version': 99 }).json()
在Python的requests库中：
- 当使用data参数并传入一个字典时，requests库默认会将这个字典进行application/x-www-form-urlencoded编码。这意味着字典中的键值对会被转换成key1=value1&key2=value2的形式发送。
- 如果字典中的某个值本身是一个JSON字符串（通过json.dumps()生成），那么这个JSON字符串会被作为整个表单编码过程中的一个普通字符串值。
- 与之相对，如果使用json参数（例如requests.post(url, json=my_dict)），requests库会将my_dict直接转换为JSON字符串，并设置Content-Type为application/json，将整个JSON字符串作为请求体发送。
因此，Python脚本实际上发送的是一个表单编码的请求体，其中一个名为data的字段，其值是一个JSON字符串。
PHP错误尝试及原因分析
在PHP中，常见的HTTP客户端库（如Requests库）在处理POST请求时，如果直接将整个数据数组传递给请求体参数，并期望它能自动识别内部的JSON结构，可能会遇到问题。
立即学习“PHP免费学习笔记（深入）”；
以下是最初的PHP尝试：
<?php // ... $headers = ['Content-Type' => 'application/json']; // 错误点之一 $data = ['data' => [ // 这是一个PHP数组 'TrackPackagesRequest' => [ // ... ]], 'action' => 'trackpackages', 'locale' => 'en_US', 'format' => 'json', 'version' => 99 ]; $response = Requests::post($url, $headers, json_encode($data)); // 错误点之二 // ... ?>
这个PHP尝试存在两个主要问题：
- $headers = [‘Content-Type’ => ‘application/json’];: 这行代码明确告诉服务器，整个请求体将是一个JSON字符串。
- json_encode($data): 这行代码将整个$data数组（包括其内部的嵌套结构）编码成一个单一的JSON字符串。
结合这两点，PHP脚本发送了一个Content-Type: application/json的请求，并且请求体是一个完整的JSON对象。然而，FedEx API期望的是一个application/x-www-form-urlencoded的请求，其中一个字段的值是JSON字符串。这种不匹配导致API返回错误信息：”CALError”: {“code”:”UNSUPPORTED.ACTION”, “message”:” is not a supported action”}，表明API无法解析或理解收到的请求格式。
PHP正确实现方案
要正确地将Python脚本的逻辑转换为PHP，我们需要模拟Python requests库发送表单编码请求的行为，并确保只有data参数的值被JSON编码。
核心思想是：
- 移除 Content-Type: application/json 请求头：让HTTP客户端库默认以application/x-www-form-urlencoded方式发送请求。
- 只对 data 参数的值进行 json_encode：将包含TrackPackagesRequest的PHP数组先json_encode成字符串，然后将其作为顶层data数组中”data”键的值。
以下是修正后的PHP代码：
<?php // 引入composer自动加载文件 $dir = __DIR__; include $dir .'/vendor/autoload.php'; // 示例追踪号 $tracking_number = '123456789'; // API请求URL $url = 'https://www.fedex.com/trackingCal/track'; // 清空或不设置Content-Type头，让Requests库默认使用form-urlencoded $headers = []; // 构建请求数据 $data = [ // 关键：只有'data'字段的值被json_encode "data" => json_encode([ "TrackPackagesRequest" => [ "appType" => "wtrk", "uniqueKey" => "", "processingParameters" => [ "anonymousTransaction" => true, "clientId" => "WTRK", "returnDetailedErrors" => true, "returnLocalizedDateTime" => false ], "trackingInfoList" => [[ "trackNumberInfo" => [ "trackingNumber" => $tracking_number, "trackingQualifier" => "", "trackingCarrier" => "" ] ]] ] ]), "action" => "trackpackages", "locale" => "en_US", "format" => "json", "version" => 99 ]; // 发送POST请求 // Requests::post函数在接收数组作为第三个参数时，默认会将其进行form-urlencoded编码 $response = Requests::post($url, $headers, $data); // 打印响应结果 print_r($response); // 解析并使用响应数据（如果成功） if ($response->success) { $responseData = json_decode($response->body, true); if (isset($responseData['TrackPackagesResponse']['packageList'][0])) { $packageInfo = $responseData['TrackPackagesResponse']['packageList'][0]; $fedex_status = $packageInfo['keyStatus']; $fedex_details = $packageInfo['statusWithDetails']; $delivery_date = $packageInfo['displayActDeliveryDt']; $delivery_time = $packageInfo['displayActDeliveryTm']; echo "FedEx Status: " . $fedex_status . "n"; echo "Details: " . $fedex_details . "n"; echo "Delivery Date: " . $delivery_date . "n"; echo "Delivery Time: " . $delivery_time . "n"; } else { echo "Package information not found in response.n"; } } else { echo "Request failed: " . $response->status_code . " - " . $response->body . "n"; } ?>
关键点与注意事项
- 理解Content-Type: 这是HTTP请求中非常重要的一个头部。它告诉服务器请求体的数据类型。application/x-www-form-urlencoded用于表单提交数据，而application/json用于发送纯JSON数据。
- Python requests.post(data=…) vs requests.post(json=…):
- data={…}：默认发送application/x-www-form-urlencoded类型的数据。如果字典值是JSON字符串，它会被作为普通字符串处理。
- json={…}：发送application/json类型的数据，并将整个字典序列化为JSON字符串。
- PHP HTTP客户端库行为: 大多数PHP HTTP客户端库（如Requests或Guzzle）在POST请求中，如果第三个参数是数组，且未明确指定Content-Type为application/json，通常会默认将其编码为application/x-www-form-urlencoded。
- API文档是金: 遇到跨语言转换问题时，最可靠的依据是目标API的官方文档。它会明确指出请求方法、URL、期望的Content-Type以及请求体的具体结构。如果文档不清晰，可以使用网络抓包工具（如wireshark、fiddler）或浏览器开发者工具（Network标签页）来分析工作中的Python脚本实际发送的HTTP请求。
- 调试技巧: 在开发和调试过程中，打印或记录HTTP请求的完整头部和请求体，可以帮助快速定位问题。
总结
从Python脚本到PHP的api调用转换，不仅仅是语法层面的翻译，更是对底层HTTP协议和特定库行为的理解。本文通过FedEx追踪API的案例，深入剖析了application/x-www-form-urlencoded和application/json这两种常见请求体格式的差异，以及如何在PHP中正确模拟Python requests库的特定行为。掌握这些知识，将有助于开发者更高效、准确地完成跨语言的API集成工作。
