Go sync.Map Range 过程中读取到的键为什么可能变化

如果你在多个 goroutine 修改 sync.Map 时调用 Range，回调里看到的键集合确实可能变化。这不是 Range 把同一个键重复遍历了，而是它本来就不承诺提供调用瞬间的一致快照：并发存储、删除或更新发生在遍历期间时，结果只代表某些时点的映射。

记住一句话：sync.Map.Range 保证一次遍历不会重复访问同一个键，但不保证你看到的是同一时刻的完整地图。需要稳定结果时，先复制快照，或者用锁保护整个读取协议。

为什么 Range 看到的键集合不稳定

Range 的回调是依次执行的，但“依次执行”不等于“冻结容器”。官方文档明确写着：它不会阻塞 Map 的其他方法，回调函数自身也可以继续操作这个 Map。因此，遍历开始后发生的 Store、Delete 和更新，都会与回调的读取时机交错。

例如原来有 k1、k2，另一个 goroutine 在遍历中执行 Store("k3", 3)。本次 Range 可能看到 k3，也可能完全看不到它；如果此时删除 k1，则可能已经回调过 k1，也可能在回调前就错过它。对同一个仍存在的键，更新前后的值也都可能成为回调参数。

用一个最小示例看清交错关系

下面的示例故意让回调短暂停顿，方便观察并发写入。它的输出顺序和是否出现 k3 都不应被写成断言；这段代码表达的是 API 边界，而不是某一次运行的固定结果。

package main

import (
    "fmt"
    "sync"
    "time"
)

func main() {
    var m sync.Map
    m.Store("k1", 1)
    m.Store("k2", 2)

    go func() {
        // 写操作与 Range 并行，故意制造不同的读取时机。
        time.Sleep(2 * time.Millisecond)
        m.Store("k3", 3)
        m.Delete("k1")
        m.Store("k2", 20)
    }()

    m.Range(func(key, value any) bool {
        // 回调只记录当时收到的参数，不把它当成最终状态。
        fmt.Printf("%v=%v\n", key, value)
        time.Sleep(3 * time.Millisecond)
        return true
    })
}

这里有三个可观察边界：k3 的插入可能赶上当前遍历，也可能错过；k1 是否出现取决于删除发生在它被回调之前还是之后；k2 可能读到 2，也可能读到更新后的 20。但在一次 Range 中，某个键不会因为这些变化而被回调两次。

哪些场景可以接受这种变化

缓存巡检、后台清理、统计采样和“尽量处理当前已有项”的任务，通常可以接受弱一致结果。它们应把逻辑写成幂等操作，并允许下一轮继续处理这次错过的键。回调里可以调用 Load 或 Delete，但要明确那是新的并发操作，不会把整个遍历变成事务。

相反，配置导出、权限快照、账单汇总、需要全量分页的接口不适合直接消费 Range。如果业务要求“同一批数据在同一个时点计算”，必须先定义快照时刻；只给 sync.Map 加一个“线程安全”的标签是不够的。

需要稳定结果时怎么做

最简单的做法是把遍历结果复制到独立切片，再让后续逻辑消费切片。这个动作只能固定“复制完成时已经读到的内容”，不能凭空得到历史时刻的数据库级快照；如果复制期间仍有写入，复制本身的边界仍需由业务接受或由锁约束。

type Entry struct {
    Key   string
    Value int
}

func snapshot(m *sync.Map) []Entry {
    var out []Entry
    m.Range(func(key, value any) bool {
        // 先复制成业务自己的值，后续排序或导出不再依赖 live map。
        k, okKey := key.(string)
        v, okValue := value.(int)
        if okKey && okValue {
            out = append(out, Entry{Key: k, Value: v})
        }
        return true
    })
    return out
}

如果“复制期间也不能有写入”是硬要求，应改用普通 map 加 sync.RWMutex，让写入和复制共用同一把锁；或者把写入集中到单 goroutine，通过消息顺序定义一致边界。不要用排序掩盖并发变化：排序只能稳定输出顺序，不能修复输入集合在读取期间改变的问题。

相关问题

Range 会不会因为并发写入漏掉一个键？ 会，新增键可能不在本次遍历结果中；这不是重复或崩溃，而是非一致快照语义。

Range 里删除当前键安全吗？ API 允许回调调用 Map 的方法，但删除只影响之后的可见状态，不会把本次遍历变成稳定快照。需要可审计的全量结果时，仍应先复制或加锁。