雲端 Mac 上的 iOS 權杖桶限流驗收:虛擬時間與突發邊界

雲端 Mac 上的 iOS 權杖桶限流驗收:虛擬時間與突發邊界

遠端執行測試時,限流案例偶爾多放行一次,很容易被歸咎於機器負載。真正的問題往往是用 sleep 猜測補充時刻:執行緒只要晚醒幾毫秒,測試就可能跨過邊界。將 iOS 請求入口的權杖桶拆成純狀態機,在雲端 Mac 上注入明確的時間,才能分辨是演算法錯誤,還是排程延遲。

先定義容量與補充契約

本文採用離散權杖桶:容量為兩個權杖,每隔 250 毫秒補充一個,建立時即為滿額;每次請求消耗指定數量,餘額不足就立即拒絕,不負責排隊。補充週期從初始化時刻起算,消耗權杖不會重設週期。

如果你需要限制短時間的突發請求,同時允許閒置後連續執行少量任務,這個模型就適用。如果需求是在任意滑動視窗內都絕不超過固定次數,權杖桶就不適合,兩者的邊界行為並不相同。

用戶端限流只能約束自身發起請求的節奏,不能取代伺服器端的配額檢查。程序重新啟動後,權杖桶會恢復滿額,因此也不能宣稱它能做到跨裝置或跨程序限流。

時間採用單調遞增的整數毫秒,不讀取日曆時間。以下實作會拒絕倒退的時間輸入,避免測試夾具中的錯誤悄悄改變狀態。

實作可注入時間的核心

將程式碼儲存為 TokenBucketChecks.swift。核心不存取網路、不讓執行緒等待,也不依賴應用程式生命週期。容量與週期必須大於零,這是建構契約;外部設定應先完成驗證,再建立實例。

import Dispatch
import XCTest

struct TokenBucket {
    let capacity: UInt64
    let interval: UInt64
    private(set) var tokens: UInt64
    private var last: UInt64

    init(capacity: UInt64, interval: UInt64, now: UInt64) {
        precondition(capacity > 0 && interval > 0)
        self.capacity = capacity
        self.interval = interval
        self.tokens = capacity
        self.last = now
    }

    mutating func take(_ cost: UInt64 = 1, at now: UInt64) -> Bool {
        guard now >= last else { return false }

        let steps = (now - last) / interval
        if steps > 0 {
            let room = capacity - tokens
            if steps >= room {
                tokens = capacity
            } else {
                tokens += steps
            }
            last += steps * interval
        }

        guard cost > 0 && cost <= tokens else { return false }
        tokens -= cost
        return true
    }
}

這裡先比較剩餘容量,再增加權杖,避免長時間閒置後直接累加而造成溢位。steps * interval 不會超過 now - last,因此推進時間時也不會超過目前輸入的時刻。

餘額達到上限後,不會儲存額外權杖,但仍會保留補充週期的相位。例如在 249 毫秒時消耗權杖,到了 250 毫秒仍會補充;這是明確選定的模型行為,不代表對連續平均速率做出精確保證。

用邊界案例取代實際等待

接著將以下測試附加到同一個檔案。第一組檢查突發容量與補充邊界,第二組檢查長時間閒置與無效輸入。每個斷言都使用獨立且容易解釋的時間點,不受雲端機器當下負載影響。

final class BucketTests: XCTestCase {
    func testBurstAndRefill() {
        var bucket = TokenBucket(capacity: 2, interval: 250, now: 0)
        XCTAssertTrue(bucket.take(at: 0))
        XCTAssertTrue(bucket.take(at: 0))
        XCTAssertFalse(bucket.take(at: 249))
        XCTAssertTrue(bucket.take(at: 250))
        XCTAssertTrue(bucket.take(at: 749))
        XCTAssertTrue(bucket.take(at: 750))
        XCTAssertFalse(bucket.take(at: 750))
    }

    func testIdleCapAndInvalidInputs() {
        var bucket = TokenBucket(capacity: 2, interval: 250, now: 0)
        XCTAssertTrue(bucket.take(2, at: 0))
        XCTAssertTrue(bucket.take(at: 10_000))
        XCTAssertTrue(bucket.take(at: 10_000))
        XCTAssertFalse(bucket.take(at: 10_000))

        let before = bucket.tokens
        XCTAssertFalse(bucket.take(at: 9_999))
        XCTAssertEqual(bucket.tokens, before)
        XCTAssertFalse(bucket.take(0, at: 10_000))
        XCTAssertFalse(bucket.take(3, at: 10_000))
    }
}

XCTMain([
    testCase([
        ("testBurstAndRefill", BucketTests.testBurstAndRefill),
        ("testIdleCapAndInvalidInputs", BucketTests.testIdleCapAndInvalidInputs)
    ])
])

使用完整 Xcode 所附的開發工具執行:

xcrun swift TokenBucketChecks.swift

以命令的結束代碼作為驗收結果,不要根據日誌中是否出現某個詞來判定成功。這份指令碼驗證的是共用的 Swift 演算法;移入 iOS 測試目標時,保留測試方法,移除指令碼末尾的 XCTMain,讓測試執行器自動探索測試案例。

建議再加入容量為一、單次扣完全部容量、非零初始化時刻,以及接近 UInt64.max 的輸入。不要為了讓失敗案例通過,就放寬成「允許幾毫秒誤差」,否則又會把確定性測試變成計時測試。

串接單調時鐘與序列化入口

正式環境的程式碼可以透過 DispatchTime.now().uptimeNanoseconds / 1_000_000 讀取毫秒。初始化與後續請求必須使用同一種時間來源,不能混入伺服器時間、牆上時鐘時間,或以啟動時刻為基準的相對計數。

多個任務共用同一個桶時,應將讀取時間、補充與扣減都放在同一個 actor 方法中,且方法內不能插入 await。若使用鎖,也必須取得鎖後才讀取時間,否則先讀取時間的呼叫可能較晚進入臨界區,被判定為時間倒退。

明確定義暫停與重建規則

本文不保證系統睡眠期間一定會累積額度;若產品要求將睡眠時間計入,就必須另選符合此語意的時鐘,並獨立測試。應用程式終止後,重新建立權杖桶會恢復滿額;若無法接受這種行為,就需要額外的持久化協定,不能只儲存餘額。

將失敗轉化為可採取行動的結論

提交前逐項核對:初始突發量恰好等於容量;補充前一毫秒會拒絕;邊界時刻會放行;跨越多個週期也不會超過容量;零成本與超容量請求都會拒絕;時間倒退不會改變狀態。

如果只有串接到應用程式後才失敗,先檢查是否建立了多個桶、是否在每次請求前重建實例,以及重試是否繞過同一個入口。若測試通過,但請求仍然過於密集,就應重新檢視容量與週期,而不是增加等待時間來掩蓋差異。

最後,分別記錄演算法測試與串接測試的結果。前者回答「狀態轉換是否正確」,後者回答「所有請求是否真的經過同一個限流入口」。將這兩件事分開,遠端測試才能維持可重現性,也更容易定位下一次回歸問題。

常見問題

為何不使用 sleep 測試權杖補充?

sleep 無法保證執行緒準時恢復。明確傳入整數時間,才能準確測試補充前一毫秒、恰好補充及跨越多個週期的情況。

權杖桶本身能保證並行安全嗎?

不能。讀取時間、補充與扣除權杖必須組成同一次序列化操作,由同一個 actor 或鎖保護。

依照專案需求,決定租用哪款 Mac

如果需要原生編譯或使用模擬器除錯,租用一台 Apple Silicon 專屬實體 Mac 進行驗證會很合適;如果是長期全職開發,而且工作地點固定,也可以比較買機的成本。按日租用更有彈性,持續使用則可考慮月租或季租。

租用遠端 Mac

接下來,依專案階段選擇方案

先查看機型、租用週期與連線方式,再決定是否租用。