Go maps.Clone 怎样复用已有缓冲空间

maps.Clone 不能把已有 map 当作“缓冲区”传进去复用。它的职责是返回一个新的浅拷贝；如果你的目标是反复刷新同一个 map，让调用方继续持有它的引用，应保留目标 map，再按数据边界选择 maps.Copy 或 clear 加 maps.Copy。

官方文档：https://pkg.go.dev/maps

需要新容器时用 maps.Clone(src)；需要复用已有目标容器时用 maps.Copy(dst, src)。如果旧键也必须消失，先执行 clear(dst)，再复制。

• maps.Clone 返回新 map，不能指定写入目标，也不会把两个 map 变成同一容器。
• maps.Copy 会覆盖同名键，但不会自动删除目标中源 map 没有的旧键。
• map 容器是浅拷贝边界；value 如果是 slice、指针或包含引用的结构体，内部数据仍可能共享。

先区分 Clone 和复用目标 map

maps.Clone 是 Go 1.21 引入的泛型 map 工具之一，签名可以概括为“接收一个 map，返回同类型 map”。官方说明明确把它定义为 shallow clone：新的键和值通过普通赋值放入新的 map。这里的“新”很重要，它意味着调用方不能传入一个已经分配好的目标，让 Clone 把结果写回那里。

为什么不能用 Clone 复用已有缓冲空间

从 API 形状看，maps.Clone(src) 没有 dst 参数；从语义看，它要返回源 map 的浅拷贝，而不是修改源 map 或某个外部容器。因此下面这种写法并不能实现“把结果放入 dst”：赋值只会让变量 dst 改为指向新 map，原来由其他对象持有的目标 map 仍然是原来的容器。

package main

import "maps"

func replaceByClone(dst map[string]int, src map[string]int) map[string]int {
	// Clone 创建新 map；返回值赋给 dst 只改变当前变量，不会修改调用方持有的容器。
	dst = maps.Clone(src)
	return dst
}

func main() {
	old := map[string]int{"old": 1}
	current := replaceByClone(old, map[string]int{"new": 2})

	// current 指向新容器，而 old 仍保留原来的键。
	_, _ = old["old"], current["new"]
}

如果调用方还把 old 传给了缓存、结构体字段或其他协作者，函数内部重新绑定 dst 不会更新那些引用。这个差异正是“返回一个新对象”和“原地刷新已有对象”的区别。

用 maps.Copy 写入已有目标

maps.Copy(dst, src) 才是面向目标 map 的 API。它会把源 map 的所有键值加入目标；如果键已存在，就用源值覆盖。它不会删除目标中多出来的键，所以适合“增量合并”或“源数据只会覆盖部分字段”的场景。

package main

import (
	"fmt"
	"maps"
)

func mergeInto(dst, src map[string]int) {
	// Copy 保留 dst 的 map 身份，只覆盖 src 中出现的键。
	maps.Copy(dst, src)
}

func main() {
	dst := map[string]int{"keep": 1, "replace": 10}
	src := map[string]int{"replace": 20, "add": 30}

	mergeInto(dst, src)
	fmt.Println(dst)
	// 结果包含 keep、replace=20 和 add=30；Copy 不会删除 keep。
}

这段策略有一个容易忽略的前提：目标中的旧键如果不在新数据里，仍然会留下。配置覆盖、局部索引更新和默认值合并通常需要这个行为；全量快照刷新则不应直接照搬。

精确刷新时先 clear 再 Copy

如果目标 map 必须在刷新后与源 map 的键集合一致，可以先使用 Go 1.21 引入的 clear 删除目标中的全部元素，再复制源数据。这样复用的是目标 map 这个容器身份，而不是要求 Clone 复用一个它并不接受的内部存储。

package main

import "maps"

func replaceAll[M ~map[K]V, K comparable, V any](dst, src M) {
	// clear 删除旧键，让结果不会残留 src 中不存在的项目。
	clear(dst)
	// Copy 在同一个目标容器中写入当前快照。
	maps.Copy(dst, src)
}

func main() {
	dst := map[string]int{"stale": 1, "shared": 2}
	src := map[string]int{"shared": 20, "fresh": 30}

	replaceAll(dst, src)
	// dst 仍是原来的 map，但键集合现在只来自 src。
	_, _ = dst["fresh"], dst["stale"]
}

需要留意两个边界。第一，clear 和 maps.Copy 之间不要把正在被其他 goroutine 读取的 map 暴露给并发访问；普通 map 的并发读写仍然需要锁或其他同步方案。第二，复用 map 身份不等于保证运行时一定不发生任何内部扩容，容量、负载和实现细节不应写成 API 承诺。

浅拷贝不会复制引用型 value

“复用已有 map”讨论的是 map 容器，而 maps.Clone 的 shallow clone 还决定了 value 的复制深度。字符串、整数等值类型通常可以直接当作独立值理解；但 slice、指针、map 或含有这些字段的结构体，复制后可能仍指向同一份底层数据。

package main

import (
	"fmt"
	"maps"
)

func main() {
	src := map[string][]int{"ids": {1, 2, 3}}
	clone := maps.Clone(src)

	// map 容器已经分开，但 slice value 仍可能共享底层数组。
	clone["ids"][0] = 99
	fmt.Println(src["ids"][0])

	// 如果 value 也必须独立，需要按业务字段显式复制 slice。
	clone["ids"] = append([]int(nil), src["ids"]...)
	clone["ids"][0] = 7
	_ = clone
}

因此，如果你的“缓冲复用”同时包含 map 结构和内部切片，应该分别定义边界：map 是否保留身份、旧键是否删除、value 是否需要深复制。单纯把 maps.Clone 换成 maps.Copy，不会自动改变引用型 value 的共享关系。

把策略封装成可核对的函数

工程里可以把“合并”和“全量替换”拆成两个名字明确的函数，避免调用方误以为 Copy 会删除旧键。泛型约束让自定义 map 类型也能保留自己的类型，而不必退化成 map[K]V。

package snapshot

import "maps"

func Merge[M ~map[K]V, K comparable, V any](dst, src M) {
	// Merge 只表达覆盖与追加，不删除 dst 的旧键。
	maps.Copy(dst, src)
}

func Replace[M ~map[K]V, K comparable, V any](dst, src M) {
	// Replace 先清空目标，再写入完整快照，目标变量和容器身份保持不变。
	clear(dst)
	maps.Copy(dst, src)
}

常见问题

maps.Clone 能不能传入 dst 参数？

不能。它的 API 只接收源 map 并返回新 map；如果必须保留目标 map 的身份，请使用 maps.Copy 或 clear 加 maps.Copy。

只调用 maps.Copy 为什么旧键还在？

因为 Copy 的语义是把源键值加入目标并覆盖同名键，不负责删除目标中源 map 没有的键。全量快照场景需要先 clear(dst)。

clear 会让 map 变成 nil 吗？

不会。它删除 map 中的元素，目标仍是可继续写入的 map；如果目标本身是 nil，仍不能直接向 nil map 赋值，调用方要先确保目标已初始化。

用 Clone 就一定能避免内部数据共享吗？

不能。Clone 是浅拷贝，slice、指针、嵌套 map 等 value 仍可能共享引用所指向的数据，需要按字段显式复制。

总结一下：maps.Clone 解决的是“得到一个新的浅拷贝”，不是“把已有 map 当作缓冲区重填”。要复用目标容器，先决定是增量合并还是精确替换，再分别使用 maps.Copy 或 clear 加 maps.Copy；最后单独检查引用型 value 和并发访问边界。