在进行跨语言的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集成工作。
