Go sync.Map Range 为什么不能当快照：并发遍历与一致性边界

线上做一段“把当前在线用户导出”的维护代码时，最容易误判的地方不是 sync.Map 能不能并发访问，而是把 Range 的结果当成了某个时刻的完整快照。只要导出期间还有 Store 或 Delete，回调看到的值就可能来自遍历过程中的不同时间点。

sync.Map.Range 保证一次回调遍历中同一个 key 不会被访问两次，但不保证所有 key/value 来自同一份一致快照；需要快照语义时，应先复制到受控的普通 map，或从数据模型上改用带锁的读路径。

先看清 Range 返回的到底是什么

下面的示例把在线用户放在 sync.Map 中。Range 的回调按顺序拿到 key 和 value；回调返回 false 时停止，但这只是提前结束遍历，并没有把 map 冻结。

var online sync.Map

online.Store("u-101", "杭州")
online.Store("u-102", "深圳")

online.Range(func(key, value any) bool {
    fmt.Println(key, value)
    return true
})

这段代码适合做“把当前能看到的条目逐个处理”。它不适合直接承诺“导出时刻的全部用户”。官方文档明确说明，Range 不对应一致快照，同一个 key 不会重复访问，但它的 value 可能来自 Range 调用期间的任意时点。

用 Store 和 Delete 复现并发交错

为了观察边界，可以让一个 goroutine 遍历，另一个 goroutine 在回调尚未结束时修改同一张表。示例里的 Store 更新已有用户，Delete 删除另一位用户；输出不能被解读为某一刻的全量名单。

var users sync.Map
users.Store("u-101", "杭州")
users.Store("u-102", "深圳")

done := make(chan struct{})
var once sync.Once
go func() {
    users.Range(func(key, value any) bool {
        fmt.Println("seen:", key, value)
        once.Do(func() { close(done) })
        return true
    })
}()

这个演示只用来建立思维模型，不能拿某一次输出顺序证明实现细节。真正应关注的是契约：Range 不阻塞 Store、Delete 等方法；如果修改发生在遍历期间，读取结果就不具备统一时间点的含义。

不要把“同一个 key 不重复”理解成“全表一致”

“同一个 key 不会被访问两次”只解决了遍历回调的重复问题，不会替你锁住其他 goroutine。比如 u-101 只出现一次，但它出现时对应的 value 可能是更新前，也可能是更新后的映射。

回调里可以操作 map，但这不是批处理事务

官方语义允许回调继续调用同一个 sync.Map 的方法。这样的写法可以实现“遇到过期项就删除”，却不能因此获得事务性批处理；回调中的修改仍会影响后续可见结果。

需要一致视图时，先复制再处理

如果目标是生成一份可审计的导出数据，可以让 Range 只负责把当时读到的内容复制到普通 map，再在遍历结束后统一排序、写文件或计算校验值。复制阶段依然不是全局快照，但后续处理不会再被 sync.Map 的并发修改改变。

func copyUsers(src *sync.Map) map[string]string {
    snapshot := make(map[string]string)
    src.Range(func(key, value any) bool {
        k, okKey := key.(string)
        v, okValue := value.(string)
        if okKey && okValue {
            snapshot[k] = v
        }
        return true
    })
    return snapshot
}

若业务真的要求“读取与写入互斥”，就不要只靠 sync.Map 的并发安全性。使用普通 map[string]string 配合 sync.RWMutex，把复制动作放在 RLock 保护范围内，语义更容易验证；这个复制后的 ordinary map 才是后续 export 的稳定输入；代价是读写会受到锁竞争影响。

发布前的四个检查点

• 这是监控式遍历，还是需要同一时刻的全量快照？
• 遍历回调是否会调用 Store、Delete 或其他业务副作用？
• 导出、批量删除、权限校验是否需要可复现的输入集合？
• 如果需要一致性，是否已经把复制或加锁边界写成测试？

相关问题：Range 的几个边界

Range 会不会按 key 排序？

不会。它不承诺 key 的顺序；需要稳定输出时，应复制后自行排序。

回调返回 false 能保证只扫描常数条吗？

不能。提前停止只影响回调是否继续，官方文档仍提示一次 Range 可能按元素数量呈 O(N) 扫描。

所有并发 map 都应该换成 sync.Map 吗？

不应该。它适合特定的读多写少或 key 集合分散的场景；需要类型安全和多个字段一起维护时，普通 map 加锁通常更清晰。

把快照语义写进代码边界

sync.Map 解决的是并发访问安全，不是报表、导出和批处理的一致性承诺。只要调用方把 Range 的结果继续交给排序、写盘或校验，就应在接口命名和测试中明确它是“遍历期间可见数据”，还是经过锁保护的“稳定快照”。边界写清楚，后续换实现时才不会把一次偶然输出当成保证。