Go maps.Collect 怎么从键值序列构造 map

Go 1.23 起，标准库 maps 包提供了 maps.Collect：只要输入是 iter.Seq2[K, V] 键值序列，就能一次构造出新的 map[K]V。最短写法是把 slices.All 产生的“索引—元素”序列直接交给它。

先看最小可用写法

package main

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

func main() {
    words := []string{"zero", "one", "two"}

    // slices.All 产生“索引、元素”键值序列。
    index := maps.Collect(slices.All(words))

    // 得到 map[int]string，例如 0 对应 zero。
    fmt.Println(index[0], index[2])
}

slices.All(words) 的类型是 iter.Seq2[int, string]，所以 maps.Collect 能推断出键类型为 int、值类型为 string。它创建新 map、依次读取序列中的键值对并返回结果。

图1：键值序列经过 maps.Collect 进入新 map 的数据流，不是软件或终端截图。

核心输入为什么是 iter.Seq2

maps.Collect 的函数签名要求键满足 comparable，值可以是任意类型。这个限制来自 map 本身：切片、map、函数等不可比较类型不能作为键。输入不是切片或数组，而是惰性产生两列数据的 iter.Seq2，因此数据来源可以是切片、树、分页流或自定义容器。

在规模较小的代码里，手写循环当然可行；当多个容器都能暴露为迭代器后，Seq2 -> map 变成统一转换边界，调用方不再需要知道底层数据究竟来自哪里。

从结构体切片构造以 ID 为键的 map

实际项目更常见的需求，是把对象列表按唯一字段建立索引。可以先写一个只负责产出键值对的迭代器，再交给 maps.Collect。

package main

import (
    "fmt"
    "iter"
    "maps"
)

type User struct {
    ID   int
    Name string
}

func UsersByID(users []User) iter.Seq2[int, User] {
    return func(yield func(int, User) bool) {
        for _, user := range users {
            // 调用方停止消费时，立即结束生产。
            if !yield(user.ID, user) {
                return
            }
        }
    }
}

func main() {
    users := []User{{ID: 10, Name: "Ada"}, {ID: 20, Name: "Lin"}}

    // Collect 创建并返回新的索引 map。
    byID := maps.Collect(UsersByID(users))
    fmt.Println(byID[20].Name)
}

这段代码把“如何遍历用户”和“如何保存结果”分开：UsersByID 决定键和值，maps.Collect 决定创建 map 并收集数据。自定义迭代器必须检查 yield 的返回值；返回 false 表示消费者已经停止，继续调用会破坏迭代协议。

重复键会发生什么

maps.Collect 内部先创建空 map，再使用与 maps.Insert 相同的赋值逻辑。若序列多次产出同一个键，后出现的值会覆盖先前值。这不是去重冲突检查；如果重复键属于业务错误，应在产生序列时显式拒绝。

func Pairs(yield func(string, int) bool) {
    // 第一次写入 go=1。
    if !yield("go", 1) {
        return
    }
    // 同一个键再次出现，最终值会变为 2。
    yield("go", 2)
}

func example() {
    got := maps.Collect(Pairs)
    // 最终 got["go"] 等于 2。
    fmt.Println(got["go"])
}

图2：重复键由后值覆盖，以及新建 map 与写入已有 map 的选择关系。

maps.Collect 与 maps.Insert 怎么选

如果目标 map 已经带有默认项或缓存内容，使用 maps.Insert 更明确：

func mergeDefaults(seq iter.Seq2[string, int]) map[string]int {
    result := map[string]int{"unknown": -1}

    // 新序列写入已有 map；冲突键采用序列中的值。
    maps.Insert(result, seq)
    return result
}

把过滤逻辑放在序列侧

maps.Collect 负责收集，不负责过滤或转换。规模扩大后，最清晰的架构是让上游迭代器处理条件与字段转换，让收集器只负责落入 map。这样既能复用过滤流水线，也不必先分配中间切片。

func ActiveUsers(users []User) iter.Seq2[int, User] {
    return func(yield func(int, User) bool) {
        for _, user := range users {
            // 示例规则：ID 小于等于零的记录不进入索引。
            if user.ID 

工程边界与运行信号

• 内存：Collect 会完整物化结果。面对无界流或极大分页数据，应分批处理，而不是无限收集。
• 容量：API 没有容量提示参数。已知元素数量且关注扩容成本时，可以 make(map[K]V, n) 后手动循环。
• 顺序：map 不提供稳定遍历顺序；若输出必须有序，应单独保留键序列或在读取时排序。
• 冲突：监控输入条数与结果键数的差值，可以发现重复键被覆盖的情况。
• 提前停止：自定义 Seq2 每次调用 yield 都应检查布尔返回值并及时 return。

测试时至少覆盖三类情况

func TestCollectUsers(t *testing.T) {
    users := []User{{ID: 1, Name: "A"}, {ID: 2, Name: "B"}}
    got := maps.Collect(UsersByID(users))

    // 验证数量，防止意外过滤或键冲突。
    if len(got) != 2 {
        t.Fatalf("unexpected size: %d", len(got))
    }
    // 验证键和值的绑定关系。
    if got[2].Name != "B" {
        t.Fatalf("unexpected user: %#v", got[2])
    }
}

除了正常输入，还应测试空序列返回非 nil 的空 map、重复键覆盖结果，以及自定义迭代器收到停止信号后是否立即结束。

常见问题

maps.Collect 可以直接接收 map 吗？

不能直接传 map，但可以用 maps.All(m) 把 map 变成 iter.Seq2。如果只是复制 map，maps.Clone 的意图更清楚。

为什么编译器说键不满足 comparable？

因为 map 键必须可比较。若希望用切片或复杂对象当键，需要先转换成字符串、整数或可比较结构体等稳定键。

Go 1.22 能使用 maps.Collect 吗？

不能。maps.Collect、maps.All 与标准 iter 包在 Go 1.23 加入；项目的 go.mod 和实际工具链都应满足这一版本边界。

可以把选择规则记成一句话：需要新 map 用 Collect，需要写入已有 map 用 Insert；重复键默认保留最后一个值。

参考：Go maps 包文档、Go maps/iter.go 源码、Go 官方博客：Range Over Function Types。