API 半夜又斷線？資深工程師的 WordPress API 串接防爆聖經：從 Rate Limit 到優雅重試 (Exponential Backoff)

哈囉，我是浪花科技的 Eric。身為一個天天在跟各種 API 打交道的工程師，我最怕的不是寫不出功能，而是半夜三點被系統告警叫醒，只因為串接的第三方 API 突然鬧脾氣，回了我一個冷冰冰的 429 Too Many Requests 錯誤。訂單沒同步、會員資料沒更新… 光想就頭皮發麻。

你是不是也遇過這種情況？滿懷信心地寫好一支 API 串接功能，在本機測試跑得順順的，一上正式環境，流量稍微大一點，整個系統就開始連環爆錯。這不是你的程式邏輯有問題，而是你忽略了 API 世界的「潛規則」—— API Rate Limit（速率限制）。

今天，我就來跟大家聊聊這個每個工程師都該懂，卻很多人都做錯的議題。我們不只會談「為什麼」，更會直接上程式碼，教你如何在 WordPress 中實作一個「優雅」且「強韌」的重試機制 (Retry Mechanism)，特別是鼎鼎大名的「指數退讓 (Exponential Backoff)」，讓你的網站就算遇到 API 塞車或暫時故障，也能像個成熟的大人一樣，冷靜處理，而不是直接崩潰給你看。

一、API Rate Limit 是什麼？為什麼它老是找我麻煩？

我們先來搞懂敵人是誰。所謂的 API Rate Limit，白話來說，就是 API 服務提供商為了保護自家伺服器，對每個用戶（通常是透過 API Key 或 IP 位址識別）在特定時間內可以發送的請求次數所做的限制。

想像一下，如果沒有這個機制，有人寫了一個無限迴圈的爛程式，每秒對 API 發送一萬次請求，那服務商的伺服器大概幾分鐘內就會被灌爆，所有人都別想用了。所以，Rate Limit 是一種保護機制，確保資源的公平分配與服務的穩定性。它不是要找你麻煩，而是維護生態系健康的必要之惡。

常見的 Rate Limit 類型

• 請求次數限制：例如，每分鐘最多 60 次請求。
• 數據流量限制：例如，每小時最多傳輸 1GB 的資料。
• 並發連線限制：例如，同時間最多只能有 5 個進行中的請求。

當你超過這個限制時，伺服器就會回傳一個 429 Too Many Requests 的 HTTP 狀態碼，有時還會在回應的 Header 中告訴你還要等多久才能再次發送請求（例如 Retry-After: 60，表示要等 60 秒）。

身為工程師的小囉嗦時間：拜託，在串接任何第三方 API 之前，第一件事就是去詳讀它的官方文件，特別是關於 Rate Limit 的章節！ 這會告訴你遊戲規則，讓你從一開始就走在正確的路上，而不是等到網站上線爆炸了才來亡羊補牢。

二、最糟的處理方式：天真地直接重試

好了，知道問題了。很多新手工程師的第一個反應是：「很簡單啊，失敗了就再試一次不就好了？」於是寫出像下面這樣的程式碼：

<?php
function simple_bad_retry_request($url, $args) {
    $response = wp_remote_get($url, $args);

    // 如果請求失敗，就立刻再試一次
    if (is_wp_error($response) || wp_remote_retrieve_response_code($response) != 200) {
        // 天真的立刻重試！
        $response = wp_remote_get($url, $args);
    }

    return $response;
}
?>

看起來好像解決了問題，對吧？錯！大錯特錯！如果 API 是因為 Rate Limit 而拒絕你，你立刻重試，只會再次撞上同一面牆，得到同一個 429 錯誤。更糟的是，這種行為就像是不斷去按一個已經塞車的電梯按鈕，只會讓 API 伺服器的負擔更重，甚至可能導致你的 IP 或 API Key 被暫時封鎖。這是一種非常「沒禮貌」且無效的作法。

三、優雅的解決方案：指數退讓 (Exponential Backoff) + Jitter

那麼，什麼才是「有禮貌」又聰明的作法呢？答案是：Exponential Backoff（指數退讓）。

這個策略的核心思想是：如果失敗了，就等待一段時間再重試。而且，每次重試的等待時間都呈指數級增長。例如：

• 第一次失敗：等 1 秒再試。
• 第二次失敗：等 2 秒再試。
• 第三次失敗：等 4 秒再試。
• 第四次失敗：等 8 秒再試…

這樣做的好處是，當 API 伺服器只是暫時性忙碌時，我們的程式會自動拉開請求的間隔，給對方喘息的空間，大大增加了下一次請求成功的機率。

為什麼還要加上 Jitter (抖動)？

光有 Exponential Backoff 還不夠完美。想像一下，如果你的網站上有 100 個使用者同時觸發了這個重試機制，他們會不會在同一個時間點（1秒後、2秒後、4秒後）同時對 API 發送請求？這就是所謂的「雷鳴群體效應 (Thundering Herd Problem)」，大家同時重試，又瞬間把 API 伺服器打掛了。

為了解決這個問題，我們需要加入 Jitter (抖動)，也就是在計算出來的等待時間上，再增加一個小的隨機值。例如，原本要等 4 秒，加上 Jitter 後可能變成等待 3.8 ~ 4.2 秒之間的隨機時間。這樣就能把大家的重試請求在時間上打散，避免同時觸發。

四、WordPress 實戰：打造一個強韌的 API 請求處理器

講了這麼多理論，我們直接來看程式碼。下面我將示範如何建立一個自訂函式 robust_remote_request，它會包裝 WordPress 內建的 wp_remote_request，並加入我們剛剛提到的「指數退讓 + Jitter」機制。

你可以把這段程式碼加到你的主題的 functions.php 檔案，或是一個自訂外掛中。

<?php
/**
 * A robust remote request function with Exponential Backoff and Jitter.
 *
 * @param string $url The URL to request.
 * @param array $args Optional. Request arguments. Same as wp_remote_request().
 * @param int $max_retries Maximum number of retries.
 * @param int $initial_delay Initial delay in milliseconds.
 * @return array|WP_Error The response or a WP_Error on failure.
 */
function robust_remote_request($url, $args = [], $max_retries = 5, $initial_delay = 1000) {
    $attempt = 0;
    $delay = $initial_delay;

    while ($attempt <= $max_retries) {
        $attempt++;

        $response = wp_remote_request($url, $args);
        $http_code = wp_remote_retrieve_response_code($response);

        // 成功的條件：不是 WP_Error 且 HTTP 狀態碼在 200-299 之間
        if (!is_wp_error($response) && $http_code >= 200 && $http_code <= 299) {
            return $response; // 成功！直接回傳結果
        }

        // 如果是客戶端錯誤 (4xx)，通常重試也沒用，直接放棄
        // 但特別處理 429 Too Many Requests
        if ($http_code >= 400 && $http_code <= 499 && $http_code != 429) {
            return new WP_Error('client_error', 'Client Error: ' . $http_code, ['response' => $response]);
        }

        // 如果已經是最後一次嘗試，就回傳錯誤
        if ($attempt > $max_retries) {
            break;
        }

        // 計算下一次的等待時間 (指數退讓)
        // pow(2, $attempt) 會是 2, 4, 8, 16...
        $delay = $initial_delay * pow(2, $attempt - 1);

        // 加入 Jitter (抖動)，這裡我們取 delay 的 50% 到 100% 之間的隨機值
        $jitter = rand($delay / 2, $delay);
        
        // 轉換為微秒 (usleep 的單位)
        $sleep_time = $jitter * 1000; 

        // 等待一下下
        usleep($sleep_time);
    }

    // 所有重試都失敗後，回傳最後的錯誤
    if (is_wp_error($response)) {
        return $response;
    } else {
        return new WP_Error('max_retries_exceeded', 'API request failed after ' . $max_retries . ' retries.', ['response' => $response]);
    }
}
?>

如何使用這個函式？

使用方法非常簡單，就像你平常使用 wp_remote_get 或 wp_remote_post 一樣，只是現在改用我們的新函式：

<?php
// 範例：呼叫一個可能不穩定的 API 端點
$api_url = 'https://api.example.com/v1/data';
$args = [
    'timeout'   => 15, // 建議設定超時時間
    'headers'   => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Content-Type'  => 'application/json; charset=utf-8',
    ],
];

// 使用我們強韌的函式來發送請求
$response = robust_remote_request($api_url, $args);

if (is_wp_error($response)) {
    // 處理錯誤，例如記錄到 log 檔
    error_log('API 請求失敗: ' . $response->get_error_message());
} else {
    $body = wp_remote_retrieve_body($response);
    $data = json_decode($body, true);
    // 成功！處理你的資料
    // ...
}
?>

五、進階策略：快取與背景處理

除了優雅重試，對於不常變動的 API 資料，我們還有更積極的優化手段：

1. 用 Transients API 做快取

如果某個 API 回傳的資料（例如：產品分類列表、天氣資訊）在一段時間內是不會變的，你就不需要每次都去請求一次。這時候 WordPress 的 Transients API 就是你的好朋友！它可以把資料暫存在資料庫中，並設定一個過期時間。

<?php
function get_api_data_with_cache() {
    $transient_key = 'my_api_data_cache';

    // 1. 先試著從快取拿資料
    $cached_data = get_transient($transient_key);
    if (false !== $cached_data) {
        return $cached_data;
    }

    // 2. 快取沒有，才真的去打 API
    $response = robust_remote_request('https://api.example.com/v1/data');
    if (!is_wp_error($response)) {
        $data = json_decode(wp_remote_retrieve_body($response), true);
        
        // 3. 把拿到的資料存到快取，設定 1 小時後過期 (3600 秒)
        set_transient($transient_key, $data, HOUR_IN_SECONDS);
        return $data;
    } 

    return false; // API 請求失敗
}
?>

這樣一來，在一小時內，無論這個函式被呼叫幾次，都只會有第一次會真的去打 API，後續的請求都會直接從資料庫快取讀取，不僅大幅提升網站速度，也大大降低了觸碰到 Rate Limit 的風險。

2. 用 Action Scheduler 處理非即時任務

對於某些不需要立即完成的任務（例如：同步大量商品資料、發送電子報），千萬不要在使用者載入頁面的當下同步執行。這會讓使用者在網頁前枯等，體驗極差。更好的作法是使用背景任務排程，例如 WooCommerce 內建的 Action Scheduler 或是 WordPress 原生的 WP-Cron。

你可以把 API 請求包裝成一個排程任務，讓它在伺服器背景默默執行。這樣就算 API 請求需要重試、等待，也不會影響到前端使用者的操作體驗。

總結

身為一個專業的 WordPress 開發者，寫 Code 從來不只是讓功能「能動」就好。當我們串接外部服務時，必須預設「網路是不可靠的」、「API 是會失敗的」。

今天我們從認識 API Rate Limit 開始，理解了為什麼不能天真地直接重試，並深入學習了「指數退讓 (Exponential Backoff) + Jitter」這個優雅又強韌的重試策略。最後，我們還探討了如何利用 Transients API 快取和背景任務排程，進一步打造出企業級的穩定串接架構。

把這些觀念和程式碼應用到你的專案中，不僅能讓你的網站更加穩定可靠，也能讓你從此告別半夜被 API 錯誤叫醒的惡夢，睡個安穩覺。這就是工程師的浪漫，不是嗎？

延伸閱讀

• 你的 WordPress 正在大開後門嗎？資深工程師的 Webhook 設計與安全驗證終極指南
• 別讓你的網站等到天荒地老！WordPress Transients API 終極指南，一招榨乾網站潛在效能
• 「別再複製貼上了！」WordPress API 串接實戰：串接 LINE / HubSpot / n8n，打造你的全自動工作流

希望這篇文章對你有幫助！如果你正在打造複雜的 WordPress 系統，需要專業的技術顧問或開發夥伴，浪花科技的團隊擁有多年的企業級 WordPress 開發與 API 串接經驗。我們樂於協助你打造穩定、高效、可擴展的數位解決方案。歡迎點擊這裡與我們聯繫，預約一次免費的技術諮詢！