API 调用返回 HTML 而非 JSON：解决自动重定向问题-php教程-PHP中文网

API 调用返回 HTML 而非 JSON：解决自动重定向问题

心靈之曲

发布： 2025-10-24 11:08:01

原创

394人浏览过

API 调用返回 HTML 而非 JSON：解决自动重定向问题

本文旨在解决在与外部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格式的响应。

AI发型设计

虚拟发型试穿工具和发型模拟器

247

查看详情

解决方案：禁用自动重定向并手动处理

解决此问题的核心在于禁用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等）进行健壮的错误处理。