Go sync.Map.Range 为什么不能当快照：并发写入、Delete 与一致性边界

缓存巡检代码里最容易出现一种误会：把 sync.Map.Range 回调走完后的键值集合，当成“这一刻的完整快照”。它并不提供这个保证。遍历期间，其他 goroutine 仍然可以调用 Store 或 Delete，回调看到的是实现允许的当前可见状态，而不是一个冻结副本。

sync.Map.Range 适合做弱一致的扫描、统计和清理提示；如果业务要求同一批数据的稳定视图，应先复制到受控容器，或改用互斥锁保护普通 map。

先区分 Range 的遍历语义和快照语义

sync.Map 解决的是多 goroutine 访问共享键值时的同步问题。它让 Load、Store、LoadOrStore 和 Delete 可以在并发场景下安全使用，但“安全访问”不等于“整个集合在一次读取中保持不变”。

Range 对每个当时可见的键最多调用一次回调；回调返回 false 后，遍历提前停止。文档同时明确，它不一定对应某个单独时刻的内容，因此不要把回调顺序或总数量当成稳定事实。

为什么 Store 和 Delete 会让扫描结果变动

下面的函数用于收集当前可见的键，但它的返回值只能理解为一次弱一致观察：

func collectKeys(m *sync.Map) []string {
    var keys []string
    m.Range(func(key, value any) bool {
        name, ok := key.(string)
        if ok {
            keys = append(keys, name)
        }
        return true
    })
    return keys
}

如果另一个 goroutine 在回调之间插入 Store("new", value)，本次扫描可能看见，也可能赶不上；如果它调用 Delete("old")，已经被回调读到的键不会从返回的切片里消失。这里没有数据竞争，但结果依然不能当成事务快照。

还要留意值的生命周期。Range 不会复制 value 指向的对象；如果 value 是指针，遍历拿到指针后对象内部仍可能被其他代码修改。容器访问安全和对象内容不变，是两层不同的问题。

三个常见场景，只有一个适合直接依赖 Range

活跃键监控通常只需要趋势，弱一致结果足够。过期清理则要接受“扫描后状态已经改变”，删除前再检查一次时间戳或版本。批量导出、对账和配置校验不能只依赖一次 Range。

需要稳定结果时，先复制再处理

一种简单边界是把 Range 只当作采集阶段：先把键和值复制到普通切片，后续排序、格式化和导出都只操作这份切片。这样能避免导出过程继续读取正在变化的共享容器，但复制动作本身仍然只是某次弱一致观察。

type Entry struct {
    Key   string
    Value any
}

func snapshot(m *sync.Map) []Entry {
    result := make([]Entry, 0)
    m.Range(func(key, value any) bool {
        name, ok := key.(string)
        if ok {
            result = append(result, Entry{Key: name, Value: value})
        }
        return true
    })
    return result
}

这份切片让后续处理与 sync.Map 解耦，却没有凭空获得全局一致性。如果业务必须知道“所有条目都属于同一个版本”，应让 value 带版本号，在复制后检查版本是否一致；检查失败就重新采集或返回重试信号。

互斥锁方案为什么更适合真正的快照

如果核心需求就是“读到同一版本的完整集合”，普通 map 加 sync.RWMutex 往往更直白。写入持有写锁，复制时持有读锁，复制完成后再释放锁；导出和排序不必一直占着锁。

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

func (r *Registry) Snapshot() map[string]Config {
    r.mu.RLock()
    defer r.mu.RUnlock()

    copied := make(map[string]Config, len(r.data))
    for key, value := range r.data {
        copied[key] = value
    }
    return copied
}

锁只保护复制过程，返回后的 copied 不再受共享写入影响。若 Config 内含切片、map 或指针，还需要对这些嵌套对象做深复制，否则只是复制了外层引用。

别把“安全”误读成“顺序”和“数量可靠”

Range 不保证遍历顺序。即便没有并发写入，也不要依赖它返回插入顺序；需要排序就把键复制出来后显式排序。并发写入时，统计总数还可能与开始或结束时的真实数量都不同。

回调里直接调用 Delete 是允许的，但它改变的是共享状态，不是对本次遍历做回滚。更稳妥的清理代码会先判断当前值是否仍匹配扫描时的版本，再删除，避免把后来写入的新值误删。

延伸问答：Range 的边界怎么落到代码评审里

Range 能保证每个键只回调一次吗？

对一次调用而言，文档保证每个当时可见的键最多回调一次，但这不等于所有并发写入都被纳入同一集合。

回调里删除当前键安全吗？

容器层面可以这样做，但删除前应再次核对版本或值，避免扫描期间同一键已经被更新。

把 Range 结果排序后就是快照吗？

不是。排序只稳定了输出顺序，没有冻结采集期间的增删变化；需要版本一致性仍要复制、校验或加锁。

什么时候直接换成 RWMutex？

当业务要求完整集合、稳定版本或可复现导出时，RWMutex 加普通 map 通常比用 sync.Map 再补一致性规则更容易验证。

一份可执行的选择清单

• 只做监控或巡检：接受弱一致，记录采样时间，不宣称是精确快照。
• 发现过期数据：扫描后再次核对版本或过期时间，再做 Delete。
• 需要批量导出：复制到独立容器，并增加版本一致性检查。
• 要求严格快照：使用 RWMutex 保护普通 map，或采用带版本的不可变配置对象。

sync.Map 的价值是降低特定读多写少场景的并发访问成本，不是替代事务或快照协议。代码评审时，只要看到 Range 后直接做对账、全量导出或批量删除，就应该追问：这个结果允许弱一致吗？如果不允许，快照边界需要在容器之外明确建立。