API 狂 Call 被鎖？別再暴力重試！ WordPress『指數退讓』優雅自救術

策略二：善用背景處理，化整為零

有些操作天生就不適合在使用者當前請求中完成，例如：當使用者註冊後，你需要同步他的資料到 CRM、EDM、ERP 等三個不同的系統。如果你在註冊流程中依序呼叫這三個 API，不僅會讓使用者等待很久，而且只要其中一個 API 慢一點或失敗，整個註冊流程就卡住了。

更聰明的作法是使用 WordPress 的排程系統（WP-Cron）或是更穩健的 Action Scheduler（WooCommerce 也在用它）。

流程變成：

1. 使用者完成註冊，立刻給他成功的回應。
2. 同時，將「同步使用者 #123 資料」這個任務丟到背景佇列 (Queue) 中。
3. Action Scheduler 會在背景默默地、一個一個地執行這些 API 同步任務。

這樣做的好處是，你可以控制背景任務的執行頻率，例如每分鐘只處理 10 個任務，將 API 呼叫的壓力平均分散到一整天，而不是集中在高峰時段。

正面對決：實作優雅的「指數退讓與抖動」重試機制

即便我們做了萬全準備，網路是不可靠的，伺服器是會打瞌睡的。當你真的收到 `429 Too Many Requests` 或 `503 Service Unavailable` 這類暫時性錯誤時，重試是必要的。但關鍵在於「如何」重試。

為什麼「暴力重試」是自殺行為？

想像一下，API 伺服器因為太忙，跟你說：「兄弟，等一下，我忙不過來了！」（回傳 429）。

暴力重試的做法是：「我不管！我再試一次！再試一次！再試一次！」這只會讓已經很忙的伺服器更加不堪重負，最後它只好把你拉黑。

指數退讓 (Exponential Backoff) 的智慧

指數退讓的邏輯很人性化：「第一次失敗，我等 1 秒再試。再失敗？那我可能要多給你點時間，我等 2 秒。又失敗？看來你真的很忙，我等 4 秒...」

等待時間以指數級增長（1, 2, 4, 8, 16...），給予對方伺服器充分的喘息空間。這是一種非常成熟和禮貌的重試策略。

更進一步：加入「抖動 (Jitter)」

想像一個情境：你的服務在同一秒有 100 個背景任務都因為 API 故障而失敗了。如果它們都採用完全相同的指數退讓策略，它們會在 1 秒後「同時」重試，2 秒後「同時」重試... 這會造成所謂的「雷鳴群體效應 (Thundering Herd)」，在特定時間點對 API 伺服器造成巨大的同步壓力。

「抖動」就是在計算出來的等待時間上，再增加一個小的隨機值。例如，原本要等 4 秒，加入抖動後，可能變成等 4.13 秒、4.52 秒、3.89 秒... 這樣就把 100 個重試請求在時間上打散了，大幅降低了瞬間的峰值壓力。

WordPress 實戰程式碼

囉嗦了這麼多，直接上 Code 比較實際。下面是一個我常用的 `safe_remote_request` 函數，它封裝了 `wp_remote_post`，並加入了指數退讓與抖動的重試機制。

/**
 * A safe wrapper for wp_remote_post with exponential backoff and jitter.
 *
 * @param string $url The URL to request.
 * @param array $args The arguments for wp_remote_post.
 * @param int $max_retries Maximum number of retries.
 * @return WP_Error|array The response or a WP_Error on failure.
 */
function safe_remote_request( $url, $args = [], $max_retries = 5 ) {
    $attempt = 0;
    $base_delay_seconds = 1; // 基礎延遲時間（秒）

    while ( $attempt < $max_retries ) {
        $attempt++;
        
        $response = wp_remote_post( $url, $args );

        if ( is_wp_error( $response ) ) {
            // 網路層級的錯誤 (e.g., cURL error)，直接重試
            if ( $attempt = 200 && $http_code = 500 && $http_code < 600 ) ) {
            if ( $attempt  $http_code ] );
    }

    // 如果迴圈跑完還是失敗（理論上會在上面回傳），回傳最後的錯誤
    return new WP_Error( 'max_retries_exceeded', 'API request failed after ' . $max_retries . ' attempts.', [ 'last_response' => $response ] );
}

/**
 * Helper function to sleep with exponential backoff and jitter.
 */
function sleep_with_backoff( $attempt, $base_delay_seconds ) {
    // 指數退讓：1, 2, 4, 8, ...
    $delay = $base_delay_seconds * ( 2 ** ( $attempt - 1 ) );

    // 加入抖動：增加一個隨機值，範圍是延遲時間的 0% 到 50%
    $jitter = $delay * ( mt_rand(0, 500) / 1000 ); 
    $sleep_time = $delay + $jitter;
    
    // 設定一個最大延遲上限，避免無限等待
    $max_sleep = 30; 
    $sleep_time = min($sleep_time, $max_sleep);
    
    // 執行延遲
    usleep( $sleep_time * 1000000 ); // usleep 的單位是微秒
}

// 使用範例
// $response = safe_remote_request('https://api.example.com/sync', [ 'body' => [ 'data' => 'some_data' ] ]);
// if ( is_wp_error($response) ) { // 處理錯誤 } else { // 處理成功的回應 }