Python转PHP：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尝试：

 'application/json']; // 错误点之一
$data = ['data' => [ // 这是一个PHP数组
            'TrackPackagesRequest' => [
                // ...
            ]],
    'action' => 'trackpackages',
    'locale' => 'en_US',
    'format' => 'json',
    'version' => 99
    ];

$response = Requests::post($url, $headers, json_encode($data)); // 错误点之二
// ...
?>

这个PHP尝试存在两个主要问题：

1. $headers = ['Content-Type' => 'application/json'];: 这行代码明确告诉服务器，整个请求体将是一个JSON字符串。
2. 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编码。

核心思想是：

1. 移除 Content-Type: application/json 请求头：让HTTP客户端库默认以application/x-www-form-urlencoded方式发送请求。
2. 只对 data 参数的值进行 json_encode：将包含TrackPackagesRequest的PHP数组先json_encode成字符串，然后将其作为顶层data数组中"data"键的值。

以下是修正后的PHP代码：

 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";
}

?>

关键点与注意事项

1. 理解Content-Type: 这是HTTP请求中非常重要的一个头部。它告诉服务器请求体的数据类型。application/x-www-form-urlencoded用于表单提交数据，而application/json用于发送纯JSON数据。
2. Python requests.post(data=...) vs requests.post(json=...):
   • data={...}：默认发送application/x-www-form-urlencoded类型的数据。如果字典值是JSON字符串，它会被作为普通字符串处理。
   • json={...}：发送application/json类型的数据，并将整个字典序列化为JSON字符串。
3. PHP HTTP客户端库行为: 大多数PHP HTTP客户端库（如Requests或Guzzle）在POST请求中，如果第三个参数是数组，且未明确指定Content-Type为application/json，通常会默认将其编码为application/x-www-form-urlencoded。
4. API文档是金: 遇到跨语言转换问题时，最可靠的依据是目标API的官方文档。它会明确指出请求方法、URL、期望的Content-Type以及请求体的具体结构。如果文档不清晰，可以使用网络抓包工具（如Wireshark、Fiddler）或浏览器开发者工具（Network标签页）来分析工作中的Python脚本实际发送的HTTP请求。
5. 调试技巧: 在开发和调试过程中，打印或记录HTTP请求的完整头部和请求体，可以帮助快速定位问题。

总结

从Python脚本到PHP的API调用转换，不仅仅是语法层面的翻译，更是对底层HTTP协议和特定库行为的理解。本文通过FedEx追踪API的案例，深入剖析了application/x-www-form-urlencoded和application/json这两种常见请求体格式的差异，以及如何在PHP中正确模拟Python requests库的特定行为。掌握这些知识，将有助于开发者更高效、准确地完成跨语言的API集成工作。