Go sync.Map.Range 能否当一致性快照：遍历语义、并发写入与统计边界

线上会话面板偶尔会出现一个让人不舒服的数字：刚刷新过的活跃用户总数，比明细列表里能看到的条目多一截。排查后发现，代码用 sync.Map.Range 一边遍历，一边让请求协程继续写入和删除。这个写法不会触发数据竞争，但它也没有承诺“这一刻的完整快照”。

先复现：安全遍历为什么仍然会得到不同总数

假设服务把在线会话放在 sync.Map 中，键是用户 ID，值是最后心跳时间。刷新接口希望同时完成两件事：统计当前在线人数，再找出一个可展示的用户。最容易写成下面这样：

var sessions sync.Map

func onlineCount() int {
    count := 0
    sessions.Range(func(key, value any) bool {
        count++
        return true
    })
    return count
}

这段代码不会像普通 map 那样因并发写入直接崩溃，回调也不会被多个协程同时调用。但如果另一个请求正好执行 Store 或 Delete，返回的 count 只是这次遍历看到的结果，不是一个带时间点的数据库快照。

Range 的三个保证，和它没有保证的那一件事

官方文档给出的边界很具体。回调是顺序调用的；如果回调返回 false，遍历停止；同一个键不会被访问超过一次。这些保证足够支撑“逐项处理一批当前可见条目”的任务。

缺失的保证同样重要：Range 不对应一致性快照。某个键如果在遍历期间被更新或删除，回调可能看到这次 Range 调用期间任意时点的映射。换句话说，结果集合可以是混合时刻的，不能拿它去证明“所有会话都在同一个版本”。

并发更新时，不要给结果附会版本含义

例如遍历先看到了 u-100 的旧心跳，随后看到了 u-101 的新状态。即便两个值都来自合法的 Store，也不能由此推导出整个集合在某个瞬间同时成立。这个区别在在线人数、库存观察值、连接数面板里尤其容易被忽略。

把“遍历处理”和“快照统计”分成两类任务

如果目标是发通知、清理过期键或寻找第一个满足条件的会话，允许集合在处理期间变化通常没有问题：

func findIdle(limit time.Duration, now time.Time) (string, bool) {
    var found string
    sessions.Range(func(key, value any) bool {
        last, ok := value.(time.Time)
        if ok && now.Sub(last) > limit {
            found, _ = key.(string)
            return false
        }
        return true
    })
    return found, found != ""
}

这里的结果语义是“本次扫描遇到的一个空闲会话”，不是“全局最早空闲会话”。如果需求升级为准确报表，就不要只靠 Range 补救，而应在写入侧维护计数、使用带锁的普通 map 建立受保护快照，或把统计交给本来就提供一致读的存储层。

提前停止不等于少扫描：O(N) 仍要留预算

回调返回 false 能停止后续业务回调，例如找到第一个匹配项就结束。但官方文档提醒，Range 即使在常量次数回调后停止，也可能仍按元素数量承担 O(N) 成本。数据量达到几十万条时，不能用“我通常很快找到目标”替代压测。

生产排查时可以先记录集合规模的近似指标、一次扫描耗时和回调命中位置。若遍历已经成为热点，优先调整数据结构和职责，不要在回调里再做网络请求、慢日志写入或长时间锁等待。

常见误区与一份可执行的检查清单

• 把“并发安全”写成“一致读取”：前者只说明方法可并发调用，后者需要额外的快照协议。
• 在 Range 回调里修改同一个 sync.Map：文档允许回调调用接收者方法，但仍要审视删除、更新对业务顺序的影响。
• 用一次遍历结果驱动扣库存或结算：这些动作需要事务、版本号或其他明确的原子边界。
• 只测空闲机器：并发写入、百万级键数量和回调耗时一起出现时，扫描成本才会暴露。

相关问题

sync.Map.Range 会锁住其他 goroutine 吗？

不会。它不会阻塞接收者上的其他方法，回调本身也可以调用同一个 sync.Map。但不阻塞不代表结果具备一致快照语义。

Range 能不能统计精确在线人数？

只能在业务接受遍历期间的近似视图时这样做。若数字用于计费、配额或审计，应采用写入侧计数、受保护快照或具备一致读的存储方案。

回调返回 false 有什么用？

它表示停止后续回调，适合找到一个目标后结束逻辑；不要因此假设底层扫描成本一定只与前几个条目有关。

总结：先写清结果的时间语义

sync.Map.Range 的价值是让并发容器可以被安全地逐项访问，而不是把动态集合冻结成快照。代码评审时先问一句“这个结果允许混合时刻吗”，就能把清理、查找、展示和结算这几类需求分开。允许近似时，给扫描耗时设预算；必须一致时，换成能表达快照边界的数据结构。