解决异步回调中会话ID丢失问题的教程

碧海醫心 2025-08-25 23:10 544浏览原创

解决异步回调中会话id丢失问题的教程

本教程旨在解决异步API回调场景中，PHP会话ID（Session ID）无法在回调页面保持一致的问题。我们将详细分析问题根源，并提供一套基于传递唯一事务标识符的解决方案，确保在服务器间回调时能正确关联用户请求与API响应，从而实现用户端状态更新，并附带代码示例和注意事项。

异步API回调中的会话管理挑战

在现代Web应用中，与第三方支付网关、短信服务或身份验证服务等外部API进行交互是常见需求。这些API通常采用异步回调（Webhook）机制来通知应用操作结果。例如，当用户发起支付请求后，支付网关会在处理完成后向应用预设的回调URL发送一个HTTP请求，告知支付成功或失败。

然而，在这种服务器到服务器的通信模式下，一个常见的问题是，回调页面（例如 response.php）无法获取到用户浏览器在发起请求时所使用的原始会话ID。这是因为回调请求是由第三方API服务器发起的，它与用户的浏览器会话完全独立，不会携带用户浏览器中的任何Cookie（包括 PHPSESSID）。因此，回调页面上的 session_start() 函数会生成一个新的、与用户无关的会话ID，导致无法将API响应与特定用户或其原始请求关联起来。

本教程将深入探讨这一问题，并提供一种健壮的解决方案，确保即使在异步回调场景下，也能有效地追踪和更新用户请求的状态。

问题分析：会话ID丢失的根源

考虑以下场景：

用户在前端页面点击按钮，通过 app.js 发送AJAX请求到 processor.php。
processor.php 处理用户请求，并向外部API发起支付请求，其中包含一个 CallBackURL 指向 response.php。
外部API处理支付，并将结果发送到 CallBackURL (response.php)。
response.php 接收API响应，并尝试使用 session_id() 将结果存储到数据库。
app.js 周期性地通过AJAX请求 fromdb.php，期望使用当前用户的 session_id() 从数据库中获取支付结果。

问题点在于：

当用户浏览器请求 processor.php 时，processor.php 能够获取到用户浏览器传递的 PHPSESSID Cookie，并使用 session_start() 恢复或创建用户会话。此时 session_id() 返回的是用户当前的会话ID。
当外部API向 response.php 发送回调请求时，这是一个新的HTTP请求，不包含用户浏览器发送的任何Cookie。因此，response.php 中的 session_start() 会创建一个全新的会话，并返回一个与用户浏览器会话完全不同的 session_id()。
结果是，response.php 将API响应与一个错误的会话ID（回调页面自身的新会话ID）存储到数据库。
fromdb.php 在用户浏览器上下文中执行，它能正确获取到用户的原始会话ID。但当它尝试使用这个ID查询数据库时，却找不到匹配的记录，因为数据库中存储的是 response.php 生成的那个不相关的会话ID。

为了解决这个问题，我们需要一个能在整个请求-回调生命周期中保持一致的事务标识符，而不是依赖于易变的会话ID。

解决方案：通过回调URL传递唯一事务标识符

核心思路是：在发起API请求时，生成一个唯一的事务标识符，将其与用户当前会话关联起来，并通过 CallBackURL 将其传递给回调页面。回调页面接收到这个标识符后，即可根据它来更新数据库中对应的事务记录。

以下是具体实现步骤：

步骤1：在发起请求前生成并存储唯一事务ID (processor.php)

在 processor.php 中，当接收到用户请求并准备调用外部API时，生成一个全局唯一的事务ID（例如 UUID），并将其与用户当前会话关联，同时在数据库中创建一条初始记录。

修改 processor.php：

首先，确保你的数据库 duka 表中有一个用于存储这个唯一事务ID的字段，例如 transaction_uuid。

<!-- processor.php -->
<?php 
session_start();
include_once "db.te.php";

// 1. 生成一个唯一的事务ID
// 建议使用更健壮的 UUID，这里简化为基于时间戳和随机数
$transaction_uuid = uniqid('txn_', true) . bin2hex(random_bytes(8)); 
$_SESSION['current_transaction_uuid'] = $transaction_uuid; // 存储在用户会话中，供 fromdb.php 使用

date_default_timezone_set('Africa/Nairobi');

$Passkey = 'bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919';

$Amount= $_POST['amount'];
$BusinessShortCode = '174379';
$PartyA =$_POST['phone'];
$AccountReference =$_POST['name'];
$TransactionDesc = 'test';
$Timestamp =date('YmdHis');
$Password = base64_encode($BusinessShortCode.$Passkey.$Timestamp);
$headers=['Content-Type:application/json; charset=utf8'];
$initiate_url='https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest';
// 2. 将唯一事务ID添加到 CallBackURL
$callBackURL ='https://c28d-197-231-178-65.ngrok.io/textEditor/response.php?transaction_uuid=' . urlencode($transaction_uuid);

// 3. 在数据库中创建初始记录，关联 transaction_uuid
// 假设 duka 表有 transaction_uuid, MerchantReqID, CheckoutReqID, ResultCode, ResultDesc 等字段
$sql = "INSERT INTO duka(transaction_uuid, Amount, PartyA, AccountReference, SessionId, Status) VALUES (?, ?, ?, ?, ?, ?);";
$stmt = mysqli_stmt_init($conn);

if (!mysqli_stmt_prepare($stmt, $sql)) {
    // 错误处理
    error_log("SQL statement failed for initial insert!");
    echo json_encode(["status" => "error", "message" => "Internal server error"]);
    exit();
} else {
    $initialStatus = 'PENDING'; // 初始状态
    // 这里我们先不获取 MerchantRequestID 和 CheckoutRequestID，因为它们是API响应的一部分
    mysqli_stmt_bind_param($stmt, "ssssss", 
        $transaction_uuid, 
        $Amount, 
        $PartyA, 
        $AccountReference, 
        session_id(), // 存储用户原始会话ID，用于调试或辅助查询
        $initialStatus
    );
    mysqli_stmt_execute($stmt);
    // 可以获取插入的ID，但我们主要依赖 transaction_uuid
}


function newAccessToken() {
    // ... (保持不变)
    $ConsumerKey = 'uhsjjsjbVGatHuJKK';
    $ConsumerSecret = 'Yh29KHAY17LKjahh';
    $credentials = base64_encode($ConsumerKey.":".$ConsumerSecret);
    $url = "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials";
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array("Authorization: Basic ".$credentials,"Content-Type:application/json"));
    curl_setopt($curl, CURLOPT_HEADER, false);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $curl_response = curl_exec($curl);
    $access_token=json_decode($curl_response);
    curl_close($curl);
    return $access_token->access_token;
}

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $initiate_url);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json','Authorization:Bearer '.newAccessToken()));
$curl_post_data = array(
    'BusinessShortCode' =>$BusinessShortCode,
    'Password' => $Password,
    'Timestamp' => $Timestamp,
    'TransactionType' => 'CustomerPayBillOnline',
    'Amount' => $Amount,
    'PartyA' => $PartyA,
    'PartyB' => $BusinessShortCode,
    'PhoneNumber' => $PartyA,
    'CallBackURL' => $callBackURL, // 使用包含 transaction_uuid 的 URL
    'AccountReference' => $AccountReference,
    'TransactionDesc' => $TransactionDesc
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
curl_close($curl);

// 可以在这里处理API的即时响应（例如 MerchantRequestID 和 CheckoutRequestID），并更新数据库
$api_response_obj = json_decode($curl_response);
if ($api_response_obj && isset($api_response_obj->MerchantRequestID)) {
    $merchantReqID = $api_response_obj->MerchantRequestID;
    $checkoutReqID = $api_response_obj->CheckoutRequestID;
    $responseCode = $api_response_obj->ResponseCode;
    $responseDesc = $api_response_obj->ResponseDescription;

    $updateSql = "UPDATE duka SET MerchantReqID = ?, CheckoutReqID = ?, ResultCode = ?, ResultDesc = ? WHERE transaction_uuid = ?;";
    $updateStmt = mysqli_stmt_init($conn);
    if (mysqli_stmt_prepare($updateStmt, $updateSql)) {
        mysqli_stmt_bind_param($updateStmt, "sssss", $merchantReqID, $checkoutReqID, $responseCode, $responseDesc, $transaction_uuid);
        mysqli_stmt_execute($updateStmt);
    } else {
        error_log("SQL statement failed for update with initial API response!");
    }
}

// 响应给前端，告知请求已发送
echo json_encode(["status" => "success", "message" => "Payment request sent."]);
?>

步骤2：在回调页面接收并使用事务ID (response.php)

response.php 现在不再依赖 session_id()，而是从 CallBackURL 的查询参数中获取 transaction_uuid。

修改 response.php：

<!-- callbackurl: response.php -->
<?php 
include_once "db.te.php";
// 不需要 session_start()，因为这里不需要维护用户会话

// 1. 从 URL 查询参数中获取 transaction_uuid
$transaction_uuid = $_GET['transaction_uuid'] ?? null;

if (!$transaction_uuid) {
    // 错误处理：缺少必要的事务ID
    http_response_code(400); // Bad Request
    error_log("Callback received without transaction_uuid.");
    exit();
}

$homepage =  file_get_contents('php://input');
$nowNow = json_decode($homepage);

if ($nowNow === null && json_last_error() !== JSON_ERROR_NONE) {
    // 错误处理：无效的JSON输入
    http_response_code(400);
    error_log("Invalid JSON received in callback for transaction_uuid: " . $transaction_uuid);
    exit();
}

// 假设 API 响应结构保持不变
if (isset($nowNow->Body->stkCallback->ResultCode) && $nowNow->Body->stkCallback->ResultCode == 0) {
    $ResultCode = $nowNow->Body->stkCallback->ResultCode;
    $MerchantRequestID =  $nowNow->Body->stkCallback->MerchantRequestID;
    $CheckoutRequestID = $nowNow->Body->stkCallback->CheckoutRequestID;
    $ResultDesc = $nowNow->Body->stkCallback->ResultDesc;
    $MpesaReceiptNumber = null;
    $Items = $nowNow->Body->stkCallback->CallbackMetadata->Item ?? [];
    foreach($Items as $Item) {
        if ($Item->Name =='MpesaReceiptNumber') {
            $MpesaReceiptNumber = $Item->Value;
        }
    }
    $status = 'SUCCESS';

} else {
    $ResultCode = $nowNow->Body->stkCallback->ResultCode ?? -1; // 默认值
    $MerchantRequestID =  $nowNow->Body->stkCallback->MerchantRequestID ?? null;
    $CheckoutRequestID = $nowNow->Body->stkCallback->CheckoutRequestID ?? null;
    $ResultDesc = $nowNow->Body->stkCallback->ResultDesc ?? 'Unknown error';
    $MpesaReceiptNumber = null;
    $status = 'FAILED';
}

// 2. 使用 transaction_uuid 更新数据库中的记录
$sql = "UPDATE duka SET ResultCode = ?, MerchantReqID = ?, CheckoutReqID = ?, ResultDesc = ?, MpesaReceiptNumber = ?, Status = ? WHERE transaction_uuid = ?;";
$stmt = mysqli_stmt_init($conn);

if (!mysqli_stmt_prepare($stmt, $sql)) {
    // 错误处理
    http_response_code(500); // Internal Server Error
    error_log("SQL statement failed for update in response.php!");
} else {
    mysqli_stmt_bind_param($stmt,"sssssss", 
        $ResultCode, 
        $MerchantRequestID, 
        $CheckoutRequestID, 
        $ResultDesc, 
        $MpesaReceiptNumber, 
        $status, 
        $transaction_uuid
    );
    mysqli_stmt_execute($stmt);
    // 返回一个 HTTP 200 OK 响应，告知 API 回调已成功接收并处理
    http_response_code(200); 
}
?>

步骤3：在前端页面获取结果 (fromdb.php 和 app.js)

fromdb.php 现在使用存储在用户会话中的 transaction_uuid 来查询数据库，而不是它自己的 session_id()。

修改 fromdb.php：

<!-- fromdb.php -->
<?php 
include_once "db.te.php";
session_start(); // 需要 session_start() 来获取用户会话中的 transaction_uuid

// 1. 从用户会话中获取 transaction_uuid
$transaction_uuid = $_SESSION['current_transaction_uuid'] ?? null;

if (!$transaction_uuid) {
    echo json_encode(["status" => "error", "message" => "No active transaction found for this session."]);
    exit();
}

// 2. 使用 transaction_uuid 从数据库中检索数据
$sql="SELECT * FROM duka WHERE transaction_uuid = ?;";
$stmt = mysqli_stmt_init($conn);

$data = null;
if (!mysqli_stmt_prepare($stmt, $sql)) {
    echo json_encode(["status" => "error", "message" => "SQL statement failed!"]);
} else {
    mysqli_stmt_bind_param($stmt, "s", $transaction_uuid);
    mysqli_stmt_execute($stmt);
    $result = mysqli_stmt_get_result($stmt);

    if (mysqli_num_rows($result) > 0) {
        $row = mysqli_fetch_assoc($result);
        // 返回所有相关数据，而不仅仅是 CheckoutReqID
        $data = $row; 
    }
}
echo json_encode($data);
?>

修改 app.js (可选，优化 getResult 逻辑):

为了更好地处理异步回调，getResult 函数应该实现一个轮询机制，直到从数据库中获取到最终结果。

// app.js
if (document.readyState == 'loading') {
    document.addEventListener('DOMContentLoaded',ready);
}else{
    ready()
}

function ready() {
        var btn = document.getElementById('sub')
        if (btn) { // 检查按钮是否存在