云端 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

下一步,按项目阶段选方案

先看机型、周期与接入方式,再决定是否租用。