本文旨在解决在与外部api交互时，尤其是在支付网关集成中，api返回html而非预期json的问题。核心原因在于http 302重定向被curl自动跟踪。教程将详细解释如何通过禁用curl的自动重定向功能 (`curlopt_followlocation => false`) 来获取原始响应，并进一步指导如何解析响应头以提取重定向uri，最终实现客户端的正确跳转。
在开发与第三方API（特别是支付网关）集成时，开发者经常会遇到一个棘手的问题：API本应返回结构化的JSON数据，却意外地收到了HTML内容。这种情况通常发生在API响应包含HTTP 302重定向时，而客户端（如cURL）默认会自动跟踪这些重定向，最终返回重定向目标页面的内容，这往往是一个HTML页面。
问题根源分析
以支付网关为例，当向支付提供商发送订单创建请求后，API的预期行为是返回一个包含支付摘要重定向URI的JSON对象。然而，如果API的响应实际上是一个HTTP 302状态码，并在Location头中设置了重定向URI，那么像PHP的cURL这样的HTTP客户端，在默认配置下，会自动跟踪这个重定向。这意味着cURL不会返回原始的302响应，而是直接请求Location头指定的URL，并返回该URL的内容。如果该URL指向一个支付页面，其内容自然是HTML。
原始代码片段中的cURL配置：
$curl = curl_init();
// ... 其他数据处理 ...
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://secure.snd.payu.com/api/v2_1/orders',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_HEADER => false, // 注意此处
CURLOPT_FOLLOWLOCATION => true, // 自动跟踪重定向
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $postdata,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization: Bearer '.$data['token']
),
));
$response = curl_exec($curl);
curl_close($curl);
return rest_ensure_response( $response );其中关键的设置是 CURLOPT_FOLLOWLOCATION => true。这个选项告诉cURL在遇到HTTP重定向（如301、302、303、307、308）时，自动发送一个新的请求到Location头指定的URL。当支付网关返回302重定向时，cURL便会执行此操作，从而获取到HTML内容。
立即学习“前端免费学习笔记（深入）”；
API文档中的提示也证实了这一点：
Note: The HTTP status code of the response is 302 and Location header is set to redirectUri, which - depending on the software used - may sometimes trigger an automatic redirect as well as receiving responses in HTML format.
这明确指出，302状态码和Location头可能导致自动重定向并接收HTML格式的响应。
解决方案：禁用自动重定向并手动处理
解决此问题的核心在于禁用cURL的自动重定向功能，从而获取到包含Location头的原始302响应。然后，我们需要手动解析响应头，提取出重定向URI，并将其返回给前端进行客户端重定向。
1. 禁用cURL自动重定向
将 CURLOPT_FOLLOWLOCATION 设置为 false。
$curl = curl_init();
// ... 其他数据处理 ...
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://secure.snd.payu.com/api/v2_1/orders',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_HEADER => true, // 必须设置为 true 以获取响应头
CURLOPT_FOLLOWLOCATION => false, // 禁用自动跟踪重定向
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $postdata,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization: Bearer '.$data['token']
),
));
$response = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE); // 获取HTTP状态码
curl_close($curl);重要提示： 为了能够读取响应头中的Location信息，必须将 CURLOPT_HEADER 设置为 true。这将使 curl_exec() 返回完整的HTTP响应（包括头和体）。
2. 解析响应并提取重定向URI
当 CURLOPT_FOLLOWLOCATION 为 false 且 CURLOPT_HEADER 为 true 时，$response 将包含完整的HTTP响应，包括状态行、响应头和响应体。我们需要解析这个字符串来获取所需的信息。
if ($http_code == 302) {
// 分离头部和身体
$header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
// 解析头部以查找 Location
preg_match('/Location:\s*(.*)\n/', $header, $matches);
if (isset($matches[1])) {
$redirectUri = trim($matches[1]);
// 此时，$redirectUri 就是前端需要跳转的 URL
// 将其返回给前端，例如通过 JSON 响应
return rest_ensure_response(array(
'status' => array('statusCode' => 'REDIRECT_REQUIRED'),
'redirectUri' => $redirectUri,
// 根据实际API文档，可能还有其他信息需要解析，例如 orderId
// 如果 body 包含 JSON，也可以尝试解析 $body
));
} else {
// 未找到 Location 头，处理错误
return rest_ensure_response(array(
'status' => array('statusCode' => 'ERROR', 'message' => '302 Found but Location header missing.'),
), 500);
}
} else {
// 如果不是 302，则尝试解析为 JSON
$decoded_response = json_decode($response, true);
if (json_last_error() === JSON_ERROR_NONE) {
return rest_ensure_response($decoded_response);
} else {
// 响应既不是 302 重定向，也不是有效的 JSON，可能是其他错误或非预期内容
return rest_ensure_response(array(
'status' => array('statusCode' => 'ERROR', 'message' => 'Unexpected API response format.'),
'raw_response' => $response // 返回原始响应以便调试
), 500);
}
}3. 前端处理重定向
将提取到的 redirectUri 返回给前端（例如 Angular 应用）。前端收到此URI后，应执行客户端重定向。
// 假设前端收到类似这样的响应
// { "status": { "statusCode": "REDIRECT_REQUIRED" }, "redirectUri": "https://secure.snd.payu.com/pay/" }
if (response.status.statusCode === 'REDIRECT_REQUIRED' && response.redirectUri) {
window.location.href = response.redirectUri;
} else {
// 处理其他状态或错误
}总结与注意事项
- 理解HTTP重定向： 遇到API返回非预期内容时，首先检查HTTP状态码。3xx系列状态码（特别是302 Found）是重定向的信号。
- cURL配置： CURLOPT_FOLLOWLOCATION 控制cURL是否自动跟踪重定向。在需要手动处理重定向URI的场景下，应将其设置为 false。
- 获取响应头： CURLOPT_HEADER 必须设置为 true 才能在 curl_exec() 的返回值中包含完整的HTTP响应头。
- 解析响应： 当 CURLOPT_HEADER 为 true 时，curl_exec() 返回的是一个包含头和体的字符串。你需要手动分割并解析头部以提取Location等信息。
- 前后端协作： 对于支付网关这类需要用户跳转的流程，后端获取到重定向URI后，通常应将其传递给前端，由前端执行最终的页面跳转，以确保用户体验的流畅性。
- 错误处理： 确保对各种可能的API响应（如非302状态码、缺少Location头、无效JSON等）进行健壮的错误处理。
通过以上步骤，您可以有效地解决API返回HTML而非JSON的问题，并正确地处理支付网关的重定向流程。
