Go sync.Map Range 为什么不是一致快照

线上做在线成员统计时，代码用 sync.Map.Range 把当前条目扫一遍。偶尔出现的现象是：本轮统计刚读到用户 A，下一轮却发现 A 的状态和关联计数不像同一时刻的数据。这个结果不一定是数据竞争，也可能只是把 Range 当成了快照接口。

结论很直接：sync.Map.Range 负责安全地遍历，不负责冻结 Map。它保证同一个 key 不会被回调两次，但遍历期间发生 Store 或 Delete 时，某个 key 看到的映射可能来自这次调用的任意时点。统计、诊断可以接受这种尽力而为的视图；审计、对账和需要成组一致的数据，应改用带锁的普通 map 或其他明确的协调机制。

线上现象：一次统计为什么会出现混合读数

先把一次调用拆成几个事实。Range 会顺序调用回调，回调返回 false 时停止；它不会重复访问同一个 key，也允许回调继续对同一个 Map 调用其他方法。但这些保证只描述遍历动作，并没有给结果附加一个统一的时间戳。

例如统计服务在 10:00:00 开始遍历，读取到 user-a=ready；另一个 goroutine 在中途把它改成 busy，或删除后重新写入。回调对其他 key 的读取可能发生在修改前，也可能发生在修改后。本轮返回的集合仍然没有重复 key，却可能是多个时点的组合。

并发写入为什么会让 Range 看到不同时间点

根因不是把 sync.Map 当成普通 map 使用，而是把“并发安全”和“一致读取”混成了两个概念。sync.Map 允许多个 goroutine 安全地加载、存储和删除；这表示操作本身不会因为并发访问而破坏容器结构，不表示一串读取自动组成事务。

把修改动作放在回调中也一样。下面的代码适合做清理或发现后停止之类的尽力而为操作，但不能把它解释成“找到一批旧值后再原子删除”：回调执行到哪个 key、其他 goroutine 何时写入，都属于并发时序。

var members sync.Map

members.Store("user-a", "ready")
members.Store("user-b", "ready")

members.Range(func(key, value any) bool {
	// 这里得到的是当前回调看到的映射，不代表同一时刻的全量状态。
	if value == "expired" {
		// 回调可以修改 m，但修改会继续影响这次遍历的可见结果。
		members.Delete(key)
	}
	return true // 继续访问尚未回调的 key。
})

另一个容易忽略的点是成本：即使回调在前几个 key 就返回 false，官方文档仍允许这次 Range 按 Map 的元素规模付出 O(N) 成本。因此“只找一个 key”既没有快照语义，也不一定等价于常数时间查找，能直接 Load 时应优先用 Load。

需要一致快照时要把写入一起协调

如果目标只是展示在线人数、输出诊断摘要或周期性刷新缓存命中概览，接受轻微漂移并在结果上注明“采样视图”通常更合适。若目标是对账、权限审计、批量导出，读者需要的是一个明确的切点，此时不能先用 Range 复制一份再声称复制结果是一致快照，因为复制期间仍可能有写入。

一种直观替代方案是让写入与复制共享 RWMutex。复制过程持有读锁，写入必须等待；复制结束后再释放锁，后续业务修改不会改变已经交给调用方的副本。

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

func (r *Registry) Put(key, value string) {
	r.mu.Lock()
	defer r.mu.Unlock()
	// 写入与 Snapshot 共用同一把锁，避免复制到半旧半新的状态。
	r.data[key] = value
}

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

	copyOfData := make(map[string]string, len(r.data))
	for key, value := range r.data {
		// 锁内完成复制，返回副本后调用方可以在锁外继续处理。
		copyOfData[key] = value
	}
	return copyOfData
}

这个选择的代价也很清楚：写入和快照复制会互相等待，数据量大时读锁持有时间会变长；但它把“一致”的定义落到了可以检查的锁边界上。若只需要单个 key 的当前值，直接 Load 通常比全量遍历更准确地表达意图。

上线前检查：别让 Range 承担事务职责

故障复盘时可以按下面的顺序确认：第一，业务是否真的需要同一时刻的全量数据；第二，回调是否调用了 Store、Delete 或触发其他副作用；第三，是否把返回顺序当成稳定排序；第四，是否因为回调提前返回就误以为扫描成本很小。只要第一项答案是“需要”，就应优先设计写入协调，而不是继续调整 Range 回调。

还要把“集合一致”和“集合内对象一致”分开。即便 Range 的 key 集合满足业务预期，value 指向的可变对象仍可能被其他 goroutine 修改；必要时应在写入侧使用不可变值、复制值或额外锁。sync.Map 是并发容器，不是事务、排序容器，也不是分页游标。

相关问题

Range 返回顺序稳定吗？

不应依赖稳定顺序。需要排序时，把可接受的读取结果收集到切片，再在协调边界外排序；需要一致切点时，先解决快照问题。

回调返回 false 会不会只遍历一个元素？

逻辑上会停止继续回调，但这不代表内部成本一定是常数。官方文档允许 Range 按元素总数承担 O(N) 工作。

用普通 map 加 Mutex 一定比 sync.Map 好吗？

不一定。sync.Map 适合特定的读多写少或 key 集合分散场景；普通 map 加锁更容易维护类型和跨字段不变量。选择应由访问模式和一致性要求决定。