云端 Mac 上的 iOS AsyncStream 缓冲与终止契约测试

云端 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 仍可能被持有。应由拥有者显式停止监听,并分别测试任务取消、主动停止和正常结束的清理路径。

用一台独享 Mac 验证你的工作流

先核对机型、节点与租期,再按天试跑。实际可用状态以控制台实时返回为准。