遠端執行測試時,限流案例偶爾多放行一次,很容易被歸咎於機器負載。真正的問題往往是用 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