Go sync.Map 怎样判断 Range 看到的数据是否完整

如果你用 sync.Map.Range 统计“当前缓存里有多少条数据”，要先记住一个关键边界：Range 保证同一个键不会被回调两次，但不保证所有键值来自同一个时间点。遍历期间发生 Store 或 Delete 时，某个键可能呈现这次遍历开始前、进行中或结束前的映射。

因此，Range 适合做遍历、清理和近似统计，不适合直接证明“这一刻的数据已经完整”。如果业务需要稳定快照，应在写入侧建立明确的同步边界，再对普通 map 副本做判断。

先把 Range 的保证和不保证分开

官方文档对 Range 的描述可以拆成三句话：

• 回调会依次收到遍历期间存在的键和值。
• 回调返回 false 时停止继续回调。
• 结果不一定对应 Map 内容的一致性快照。

“同一个键不重复”不等于“所有键来自同一时刻”。例如遍历先看到了 user-a，随后另一个 goroutine 更新了 user-b，回调接收到的两个键就可能反映不同时间的状态。

用一个缓存盘点例子看懂并发变化

下面的函数想统计非空缓存项。代码本身可以安全调用，但返回的数量只能解释为“本次遍历观察到的数量”，不能当成并发更新期间的精确总数。

package main

import (
    "fmt"
    "sync"
)

func countReady(m *sync.Map) int {
    count := 0
    m.Range(func(key, value any) bool {
        // 统计本次遍历实际看到的值，而不是声明一个全局一致快照。
        if value != nil {
            count++
        }
        return true
    })
    return count
}

func main() {
    var cache sync.Map
    cache.Store("a", "ready")
    cache.Store("b", "ready")

    fmt.Println(countReady(&cache))
    // 其他 goroutine 仍可在 Range 期间 Store 或 Delete。
}

如果另一个 goroutine 在回调执行期间删除 a，本次回调仍可能已经拿到 a 的旧映射；如果它在遍历尚未触及 b 时更新 b，回调也可能拿到更新后的值。两种情况都符合 Range 的语义。

为什么不能用 Range 的数量判断数据完整

常见误区是先调用 Range，再把计数与“应有数量”比较：

func isComplete(m *sync.Map, expected int) bool {
    seen := 0
    m.Range(func(_, _ any) bool {
        // 提前返回只能停止回调，不能把 Range 变成快照读取。
        seen++
        return seen 

这个写法只能回答“遍历过程中回调了多少次”。它无法回答：遍历开始前是否已经有键被删除；遍历过程中是否有新键写入但尚未被看到；不同键是否属于同一业务版本；读到的值是否与另外一份元数据处于同一时刻。

另外，文档明确指出，即使回调很快返回 false，Range 也可能按 Map 中元素数量产生 O(N) 的工作量，所以不要把“找到几个键就停”理解为固定复杂度保证。

需要稳定结果时，先建立快照边界

如果业务是生成报表、校验一批配置或判断一轮任务是否完成，建议让写入和快照复制共享一个版本边界。下面是一个小型封装：普通 map 受互斥锁保护，复制完成后再在锁外分析。

type SnapshotMap struct {
    mu sync.RWMutex
    data map[string]string
}

func (s *SnapshotMap) Snapshot() map[string]string {
    s.mu.RLock()
    defer s.mu.RUnlock() // 复制完成后释放读锁，避免把分析过程放进临界区。

    snapshot := make(map[string]string, len(s.data))
    for key, value := range s.data {
        // 复制值而不是把内部 map 直接交给调用方，保持写入边界清晰。
        snapshot[key] = value
    }
    return snapshot
}

如果仍然需要使用 sync.Map，可以在写入方维护一个单调递增的版本号，先记录开始版本，再完成遍历，最后检查版本是否变化。版本变化时只能说明本轮观察期间有写入活动，不能自动把不一致结果变成一致结果；通常应重新生成快照，或改用锁保护的普通 Map。

回调里能不能继续操作同一个 Map

可以。官方实现说明回调本身可以调用接收者上的其他方法，包括再次访问这个 sync.Map。但“允许调用”不代表“结果会更一致”：回调中的 Store 或 Delete 仍然会改变后续观察到的内容，也会让阅读代码的人更难判断遍历边界。

工程上更清晰的做法是：回调只收集键值或执行无副作用的判断，把写入、删除和耗时分析放到 Range 之后。若必须在回调中删除，先明确它是清理动作，而不是依靠一次 Range 完成一致性校验。

最后用一张表决定方案

常见问题

Range 会不会漏掉一个已经存在的键？

并发 Store 和 Delete 发生时，结果不对应一致快照，因此不能按“开始时的完整键集合”去推断。若必须核对完整集合，需要先建立不会在核对期间变化的快照。

把 Range 放进循环重试就能得到准确结果吗？

不能。重试只能降低某些瞬时变化的影响，不能证明两次遍历之间没有变化。应把重试条件和版本号、锁或快照机制绑定起来。

普通 map 加 RWMutex 会不会更容易维护？

如果业务需要类型安全、复合不变量或一致快照，普通 map 加锁通常更直接。sync.Map 更适合读多写少且键集合或访问模式符合其设计目标的场景。

总结一下：sync.Map.Range 解决的是并发安全的遍历，不是事务快照。看到的数量、值和键集合都应被理解为一次并发观察；需要“完整”“同版本”“精确总数”时，把同步边界前移到写入和快照构建阶段。