maps.All 生成映射迭代器的快照语义

先说结论：maps.All 不是调用时快照

不少人看到 maps.All(m) 返回一个迭代器，会自然地理解成“先把当前键值对封装起来，之后再慢慢读取”。实际语义恰好相反：maps.All 返回的是绑定原 map 的惰性迭代器，调用它时不会复制键值对；真正的 range 要等迭代器被消费时才开始。

因此需要区分两个时刻：创建迭代器的时刻，以及消费迭代器的时刻。两者之间如果修改了原 map，消费端通常看到的是修改后的内容，而不是创建迭代器时的旧状态。

图1：maps.All 迭代器与原 map 的静态关系图，它不保存独立元素副本。

为什么它会反映后续修改

标准库中 maps.All 的核心实现很短：它返回一个函数，函数真正执行时才对传入的 map 做 range。这个闭包保留的是原 map，而不是一份预先收集好的键值对。

package main

import (
    "fmt"
    "maps"
)

func main() {
    m := map[string]int{"a": 1}

    // 此处只创建惰性迭代器，还没有遍历 map
    seq := maps.All(m)

    // 在消费迭代器前修改原 map
    m["a"] = 2
    m["b"] = 3

    // Collect 现在才消费 seq，所以得到修改后的值
    got := maps.Collect(seq)
    fmt.Println(got["a"], got["b"]) // 2 3
}

这个例子也说明，maps.Collect(maps.All(m)) 的确会创建一个新 map，但快照发生在 Collect 消费迭代器期间，而不是 All 被调用时。如果这两个调用之间存在修改，结果以消费时观察到的 map 为准。

复用同一个迭代器会发生什么

iter.Seq2 本质上是函数。只要没有并发冲突，同一个 seq 可以被再次消费，而每次消费都会重新对原 map 进行一次遍历。它不是一次性缓存，也不会记住上次迭代到哪里。

package main

import (
    "fmt"
    "maps"
)

func main() {
    m := map[string]int{"version": 1}
    seq := maps.All(m)

    // 第一次消费读取当前值
    first := maps.Collect(seq)

    // 修改原 map 后再次消费同一个迭代器
    m["version"] = 2
    second := maps.Collect(seq)

    fmt.Println(first["version"], second["version"]) // 1 2
}

如果业务要求“同一批处理始终看到相同数据”，不要把 seq 保存起来当快照。应先复制 map，再从副本创建迭代器。

迭代过程中修改 map 的边界

Go 语言规范明确规定，map 的遍历顺序未指定，也不保证两次遍历顺序一致。遍历过程中删除一个尚未到达的键，该键不会再产生；新增一个键，则它可能在本轮出现，也可能被跳过。依赖其中任一种结果都属于不稳定写法。

for key, value := range maps.All(m) {
    // 不要让业务正确性依赖新增键是否会在本轮出现
    if value == 0 {
        delete(m, key)
    }
}

同一个 goroutine 中按语言规则删除当前项可以工作，但一边遍历一边新增、重写并据此推断完整结果，往往难以维护。更清晰的做法是先收集要变更的键，结束遍历后再统一修改。

需要稳定快照时怎样写

只要求隔离后续对外层 map 的增删改时，可以在明确的时点调用 maps.Clone。随后无论原 map 怎样变化，从副本创建的迭代器都只观察副本。

package main

import (
    "fmt"
    "maps"
)

func main() {
    m := map[string]int{"a": 1}

    // 在这里固定外层 map 的快照
    snapshot := maps.Clone(m)
    seq := maps.All(snapshot)

    // 后续修改原 map 不影响 snapshot
    m["a"] = 99
    got := maps.Collect(seq)
    fmt.Println(got["a"]) // 1
}

maps.Clone 是浅拷贝。如果值是 slice、map、指针或包含引用字段的结构体，副本中的值仍可能与原数据共享底层对象。需要深度隔离时，应按业务类型显式复制嵌套对象。

图2：maps.All 保持与原 map 的连接；maps.Clone 复制外层 map，但嵌套引用值仍可能共享。

既要快照又要稳定顺序

map 本身没有稳定遍历顺序。测试输出、签名计算或可重复构建如果还要求固定顺序，可以先复制 map，再排序键，最后生成有序切片。

package main

import (
    "fmt"
    "maps"
    "slices"
)

type Pair struct {
    Key   string
    Value int
}

func main() {
    m := map[string]int{"b": 2, "a": 1}

    // 先固定外层 map，再对副本的键排序
    snapshot := maps.Clone(m)
    keys := slices.Sorted(maps.Keys(snapshot))

    // 按稳定键序生成真正有序的结果切片
    pairs := make([]Pair, 0, len(keys))
    for _, key := range keys {
        pairs = append(pairs, Pair{Key: key, Value: snapshot[key]})
    }

    fmt.Println(pairs) // [{a 1} {b 2}]
}

这里的顺序来自排序后的键切片，不来自 maps.All。如果只是需要一个独立但无序的新 map，直接使用 maps.Clone 或立即执行 maps.Collect(maps.All(m)) 即可。

并发场景不能靠“惰性”规避锁

maps.All 不会把普通 map 变成线程安全的数据源。一个 goroutine 消费迭代器时，另一个 goroutine 对同一 map 写入，仍然属于并发读写风险，可能触发运行时错误或数据竞争。

常用做法是在锁内复制一份快照，再在锁外遍历副本。这样可以缩短持锁时间，也能让本轮处理看到一致的外层 map 状态。

mu.RLock()
// 在读锁保护下固定当前外层 map
snapshot := maps.Clone(shared)
mu.RUnlock()

// 锁外安全消费副本的迭代器
for key, value := range maps.All(snapshot) {
    _ = key
    _ = value
}

常见问题

maps.All(nil) 会怎样？

nil map 的遍历次数为零，因此消费 maps.All(nilMap) 不会产生任何键值对，也不会因为遍历本身而 panic。

maps.Collect(maps.All(m)) 等价于 maps.Clone(m) 吗？

对普通 map 来说，两者都会得到新的外层 map，且都是浅层复制。不过前者强调“消费迭代器后收集”，后者更直接表达“此刻复制 map”的意图。只为获得快照时，maps.Clone 通常更易读。

可以依赖 maps.All 的遍历顺序吗？

不可以。官方文档明确说明迭代顺序未指定。需要稳定顺序时，应使用 maps.Keys 收集键，再用 slices.Sorted 排序。

一句话如何记住它？

maps.All 是“以后遍历这张 map 的函数”，不是“现在复制这张 map 的结果”。先决定一致性时点，再选择直接迭代、立即收集、浅克隆或业务级深拷贝。

参考资料

• Go 标准库 maps 包文档：https://pkg.go.dev/maps
• Go 标准库 maps/iter.go 源码：https://go.dev/src/maps/iter.go
• Go 语言规范 For statements with range clause：https://go.dev/ref/spec#For_range