云端 Mac 上验收 iOS 环形缓冲区：回绕、满空与批量读写

在 Windows 上写好数据接收逻辑，转到云端 Mac 运行 iOS 测试后，环形缓冲区可能只在连续写满、读走一部分、再次写入时丢数据。单次入队出队看不出这种错误。下面把缓冲区抽成纯 Swift 类型，在 OSXMesh 云端 Mac 的终端验证，再把同一组断言移入应用测试目标。

先固定满空与失败语义

本文使用固定容量、先进先出的整数缓冲区：容量必须大于零；满时拒绝新元素，不覆盖旧数据；空时读取返回 nil。批量写入允许部分成功，返回实际接收数量，剩余输入交还调用方处理。

这不是唯一设计，但必须先选定一种。若产品需要覆盖最旧数据，应另写类型和断言，不能让同一个 append 在不同调用点暗中切换语义。

环形缓冲区的正确性不只是“不越界”：失败操作不能改变状态，成功读取的顺序必须与接收顺序一致。

用 head 表示下一次读取位置，用 count 区分满空。逻辑尾部由两者推导，因此全部存储槽都可使用。示例限定容量上限，避免索引相加溢出，也防止测试误传巨大容量。

写出能独立执行的最小实现

新建 RingCheck.swift，放入下面的代码。它只依赖标准库，不需要模拟器，也不需要工程签名。先执行 swift --version 留下工具链信息；若命令不可用，先在图形界面完成开发工具安装与初始化。

struct IntRing {
    let capacity: Int
    private var storage: [Int?]
    private var head = 0
    private(set) var count = 0

    init(capacity: Int) {
        precondition((1...1_000_000).contains(capacity))
        self.capacity = capacity
        storage = Array(repeating: nil, count: capacity)
    }

    mutating func append(_ value: Int) -> Bool {
        guard count < capacity else { return false }
        storage[(head + count) % capacity] = value
        count += 1
        return true
    }

    mutating func pop() -> Int? {
        guard count > 0 else { return nil }
        let value = storage[head]!
        storage[head] = nil
        head = (head + 1) % capacity
        count -= 1
        return value
    }

    mutating func appendBatch(_ values: [Int]) -> Int {
        var accepted = 0
        for value in values {
            guard append(value) else { break }
            accepted += 1
        }
        return accepted
    }

    func snapshot() -> [Int] {
        (0..<count).map {
            storage[(head + $0) % capacity]!
        }
    }
}

这里的强制解包依赖内部不变量：逻辑有效区间内一定有值。若实现破坏了不变量，测试应直接失败，而不是用默认值掩盖错误。读取后清空槽位，也便于未来改成引用类型时及时释放对象。

用小容量逼出回绕错误

把以下代码接在文件末尾。容量三的场景先写满，再读取两个元素，最后跨过数组尾部写入。容量一则能暴露“预留一个空槽”与当前容量契约混用的问题。

var ring = IntRing(capacity: 3)
precondition(ring.appendBatch([10, 20, 30]) == 3)
precondition(!ring.append(99))
precondition(ring.snapshot() == [10, 20, 30])
precondition(ring.pop() == 10)
precondition(ring.pop() == 20)
precondition(ring.appendBatch([40, 50, 60]) == 2)
precondition(ring.snapshot() == [30, 40, 50])
precondition(ring.pop() == 30)
precondition(ring.pop() == 40)
precondition(ring.pop() == 50)
precondition(ring.pop() == nil)
precondition(ring.count == 0)

var single = IntRing(capacity: 1)
precondition(single.pop() == nil)
precondition(single.append(7))
precondition(!single.append(8))
precondition(single.pop() == 7)
precondition(single.appendBatch([]) == 0)

特别检查拒绝写入后的快照。仅断言返回 false 不够：错误实现可能先推进索引，再发现容量已满。空读也一样，不能把下一次有效读取的位置悄悄移动。

用固定种子逐步对照参考队列

边界用例通过后，再追加模型测试。参考模型使用普通数组，它的头部删除虽然较慢，但这里容量很小，优先保证容易审查。每一步都比较内容和数量，比只核对最终结果更容易定位首次偏差。

var seed: UInt64 = 0x5EED
func next() -> UInt64 {
    seed = seed &* 6364136223846793005 &+ 1
    return seed
}

for capacity in [1, 2, 3, 7] {
    var tested = IntRing(capacity: capacity)
    var model: [Int] = []

    for step in 0..<20_000 {
        if (next() >> 32) % 2 == 0 {
            let value = Int(next() % 10_000)
            let accepted = model.count < capacity
            precondition(tested.append(value) == accepted)
            if accepted { model.append(value) }
        } else {
            let expected = model.isEmpty ? nil : model.removeFirst()
            precondition(tested.pop() == expected)
        }

        precondition(
            tested.snapshot() == model,
            "capacity=\(capacity), step=\(step)"
        )
        precondition(tested.count == model.count)
    }
}

运行 swift RingCheck.swift，正常结束且没有断言失败才算通过。此处没有性能结论；循环次数只是测试规模。批量路径还应补充剩余空间为零、恰好足够、少一个槽位三组显式用例，并核对返回数量与输入后缀。

生成器使用高位决定操作，避免简单生成器低位规律造成机械交替。复现时保留初始种子、容量和失败步骤，不要只记录失败瞬间的种子。

接入工程并守住适用边界

独立脚本通过后，将类型移入业务模块，把断言改为测试框架的相等断言。至少保留下面三类检查：

• 状态约束：数量始终位于零与容量之间，失败操作前后的快照完全相同。
• 顺序约束：重复值和负数也要按接收顺序返回，不能用集合比较替代数组比较。
• 批量约束：返回值等于实际写入数量，未接收后缀不能被调用方当作已消费。

若业务提供清空接口，还要分别在空、满和已回绕状态清空，再重新写满，确认旧数据不会复现。若元素改为泛型，应另外检查引用释放，不能把整数测试的通过等同于生命周期正确。

这个实现只适合顺序访问，不是无锁队列，也不适合直接放进有实时约束的音频回调。共享给多个任务时，先明确同步边界，再测试并发行为。最终应提交实现、边界用例和固定种子模型测试，让下一次索引算法调整仍能得到相同的验收结论。

常见问题