雲端 Mac 上的 iOS AsyncStream 緩衝與終止契約測試
你的 iOS 頁面透過 AsyncStream 接收進度事件,偶爾操作時一切正常,連續觸發後卻會跳過中間狀態;離開頁面後,底層監聽器也仍在運作。先別增加等待時間。在 VPSPull 雲端 Mac 上固定事件產生與消費的順序,分別驗證緩衝、結束與清理契約,比反覆點擊遠端桌面更容易找出問題。
先決定哪些事件可以丟棄
進度百分比通常只需要最新狀態,但付款確認或檔案交付紀錄不能任意丟失。先為串流訂下三個條件:哪些值必須送達、事件積壓時如何處理,以及由誰負責停止生產者。不要讓預設緩衝策略替業務需求做決定。
unbounded 會保留尚未消費的元素,但持續產生事件可能讓記憶體用量不斷增加;bufferingNewest(2) 保留最新的兩個元素;bufferingOldest(2) 保留最早的兩個待消費元素。這裡的容量是元素數量,不是位元組數,大型物件仍可能占用大量記憶體。
有界緩衝不等於背壓。AsyncStream 的 yield 不會等待消費者騰出空間;如果業務要求無損傳輸,就需要另外建立確認、限速或持久化機制。
先只測試一個消費者。多個工作共同消費同一個串流,不能直接視為「每個訂閱者都會收到全部事件」的廣播模型。
建立不靠排程運氣的測試夾具
在已備妥 Swift 工具鏈的終端機中執行:
mkdir StreamContract
cd StreamContract
swift package init --type library --name StreamContract
swift --version
將產生的測試檔案內容替換為下列 XCTest 測試。檔案放在 Tests/StreamContractTests/StreamContractTests.swift;如果產生的範本還有其他測試檔案,先移除其中的範例測試,避免把無關結果混入報告。
import XCTest
final class StreamContractTests: XCTestCase {
func testNewestBufferDrainsAfterFinish() async {
let pair = AsyncStream<Int>.makeStream(
bufferingPolicy: .bufferingNewest(2)
)
pair.continuation.yield(1)
pair.continuation.yield(2)
switch pair.continuation.yield(3) {
case .dropped(let value):
XCTAssertEqual(value, 1)
default:
XCTFail("Expected the oldest buffered value to be dropped")
}
pair.continuation.finish()
var iterator = pair.stream.makeAsyncIterator()
let first = await iterator.next()
let second = await iterator.next()
let end = await iterator.next()
XCTAssertEqual(first, 2)
XCTAssertEqual(second, 3)
XCTAssertNil(end)
switch pair.continuation.yield(4) {
case .terminated:
break
default:
XCTFail("Expected a terminated stream")
}
}
}
接著執行 swift test。這個測試先產生事件、再消費事件,刻意讓緩衝區溢位,不必靠休眠來猜測排程順序。如果工具鏈沒有 makeStream,應先確認 Swift 版本,或改用初始化閉包取得 continuation,不能為了「相容」而刪除溢位斷言。
驗收被丟棄的值,不只看消費結果
只斷言最後收到 2、3 並不夠:錯誤的實作可能主動過濾 1,碰巧得到相同結果。檢查 yield 回傳的 .dropped 值,才能確認事件是在緩衝策略這一層被丟棄。
接著複製測試,改用 bufferingOldest(2)。第三次 yield 應回報丟棄 3,消費結果應為 1、2。將這些預期寫成獨立的測試名稱,不要在測試內依照實際輸出調整答案。
還要增加一個邊界案例:容量設為零,且沒有正在等待的消費者時,yield 的元素會被丟棄。零容量不保證同步交接。如果測試提前啟動消費者,就必須建立「已經在等待」的同步訊號,否則結果會隨工作排程而變動。
對於實際物件,記錄穩定的事件編號即可。不要把完整承載資料寫入日誌;資料較大時,記錄編號、丟棄次數與緩衝策略,就足以進行分析。
分開測試 finish、取消與提早離開
finish() 表示不再接受新元素,不代表立即丟棄已緩衝的元素。上面的測試刻意驗證先讀完 2、3,接著 next 才回傳 nil;結束後的 yield 則應回傳 .terminated。
取消測試要另外建立夾具:讓消費工作等待 next,取消該工作,再等待工作退出。使用執行緒安全的計數器或測試預期記錄 onTermination,確認終止原因是取消,也確認底層監聽器已停止。設定有限的逾時時間只是為了防止測試卡住,並不是業務行為正確的證據。
提早離開必須有明確的擁有者
迴圈中的 break 只會離開迴圈。如果其他物件仍持有串流或 continuation,不能據此斷言監聽器已經釋放。為轉接器提供明確的 stop 操作,由頁面或服務擁有者呼叫,再檢查取消註冊的次數。
onTermination 可能在並行執行環境中執行。清理閉包擷取的狀態必須支援並行存取;不要直接修改只能由主執行緒存取的介面物件,也不要在持有內部鎖定時呼叫 finish,再讓終止回呼取得同一把鎖。
用失敗矩陣完成驗收,而不是延長等待
最後至少保留四類驗收測試:最新值緩衝淘汰舊值、最早值緩衝拒絕新值、正常結束後排空,以及取消後停止產生事件。每一類都要檢查值、結束狀態與清理次數,避免「測試通過,但資源仍在運作」。
再用假的監聽器製造停止時的競態:stop 之後再觸發一次回呼,轉接器必須安全地忽略它,或收到 terminated,不能重複交付業務事件。連續呼叫 stop 也應保持冪等,不得重複取消註冊同一個監聽控制代碼。
提交時一併保存工具鏈版本、測試命令與失敗案例名稱。如果固定順序的測試穩定,但實際頁面仍會丟失事件,下一步應檢查事件來源轉接器與消費者的處理速度;如果夾具本身不穩定,先修正同步方式,不要用更長的休眠把競態藏起來。
常見問題
bufferingNewest 會讓生產端等待消費端嗎?
不會。緩衝區滿時會淘汰較舊的元素,yield 回報遭捨棄的值,但不等待消費端騰出空間。若需要有界且無損的傳輸,必須另外設計確認或流量控制機制。
消費端執行 break 後,監聽器一定立即釋放嗎?
不一定。break 只離開迴圈,串流與 continuation 仍可能被持有。應由擁有者明確停止監聽,並分別測試工作取消、主動停止及正常結束的清理路徑。