Go mutex复制后锁状态失效的代码审查要点

在审查一个带缓存字段的 Go 结构体时，我最先看的不是字段数量，而是它是否嵌入了 sync.Mutex。只要这个结构体被按值传入函数、作为值接收者调用方法，或从切片、map 中取出再赋值，锁和业务数据就可能被一起复制。结果通常不是立刻 panic，而是两份对象各自拿着一把看似正常、实际互不协调的锁。

官方资料：https://pkg.go.dev/sync

审查结论可以先记成一句话：包含 mutex 的类型默认采用指针语义，首次使用后不要复制；需要复制业务数据时，把可复制的数据与锁拆开。

先分清：复制的是业务值，还是锁的归属

sync.Mutex 的零值可以直接使用，但官方约束是“首次使用后不得复制”。这里的重点不是锁字段看起来有多大，而是锁的内部状态和它保护的字段必须属于同一个对象。下面这段代码里，Snapshot 的值接收者会复制整个 counter，方法拿到的是副本的锁和副本的计数。

type counter struct {
	mu sync.Mutex
	n  int
}

// 值接收者会复制 counter，锁和 n 都不再属于调用方原对象。
func (c counter) Snapshot() int {
	c.mu.Lock()
	defer c.mu.Unlock() // 释放的是副本上的锁
	return c.n
}

// 指针接收者操作同一个 counter，锁与业务字段保持同一归属。
func (c *counter) Add(delta int) {
	c.mu.Lock()
	defer c.mu.Unlock() // 即使中途返回，也保证配对释放
	c.n += delta
}

审查时还要区分“初始化前复制”和“使用后复制”。用字面量创建两个独立的零值对象并不等于复制已使用的锁；真正危险的是已经参与过 Lock、Unlock 或被并发调用的实例，又经过赋值、返回、参数传递或容器遍历。

三种代码形态的审查对比

我通常把候选写法分成三类。第一类是值接收者或值参数，写起来像普通数据模型，但每次调用都可能复制锁；第二类是指针接收者和指针参数，调用方共享同一个锁，适合带可变状态的对象；第三类是只复制业务快照，锁留在管理对象内部，适合需要对外返回数据的 API。

更隐蔽的复制来自容器：for _, item := range items 会把元素复制到 item；v := m[key] 也可能把 map 中的结构体值取成副本；返回 counter 或把它塞进接口，则要继续检查后续的动态值传递。代码审查不能只搜 func 签名，还要沿着数据流看这些赋值点。

把修复方案落到指针与不可复制边界

最小修复通常是把构造函数、方法接收者和需要共享状态的参数都改为指针，并保留零值可用。切片也改成指针元素，避免遍历时复制元素；如果业务只需要导出数据，就在锁内读取字段，返回一个不包含 mutex 的快照结构。

type CounterView struct {
	Value int
}

// Snapshot 只把业务结果带出锁的边界，不暴露含锁对象。
func (c *counter) Snapshot() CounterView {
	c.mu.Lock()
	defer c.mu.Unlock() // 先读完受保护字段，再释放锁
	return CounterView{Value: c.n}
}

// 指针切片避免 range 把含锁元素复制到局部变量。
func total(items []*counter) int {
	total := 0
	for _, item := range items {
		// 每次调用都落到原对象，而不是 range 副本。
		total += item.Snapshot().Value
	}
	return total
}

如果类型必须提醒工具链“不要复制”，可以在设计文档中明确指针语义，并让 go vet 的 copylocks 报告成为提交门禁。不要为了绕过提示而把锁藏进接口或改成不相关的字段名；那只会把归属问题推迟到运行时。

用 go vet 收口，再复查几个边界

# 检查整个模块中可能复制锁的路径。
go vet -copylocks ./...

# 也可以把检查放进提交前脚本，减少值接收者回归。
go vet ./...

官方的 copylock 分析器专门检查锁被按值传递的情况，但它是辅助线索，不代替人工判断。看到报告后先定位复制语句，再决定是改成指针、改成快照，还是把锁和数据拆成两个类型。确认修复后要复查 Lock/Unlock 是否仍然配对、是否可能对 nil 指针调用，以及锁覆盖的数据范围是否足够。

几个边界容易误判：只读方法也可能需要指针接收者，因为“读”仍可能通过锁同步；把 mutex 放入接口并不会让复制安全；sync.RWMutex、sync.Once、sync.WaitGroup 等同步类型也应按同一不可复制思路处理。只有在明确的新对象尚未使用、且复制不会形成共享状态时，才谈得上安全复制。

常见疑问

只读方法为什么也不能用值接收者？ 因为方法调用本身已经复制结构体，锁保护的不是原对象；即便当前只读取，也失去了与写入方的同步关系。

能不能把 mutex 指针放进结构体再复制？ 这会让多个对象共享同一把锁，但业务字段仍然可能已经分裂，除非共享锁与被保护数据的归属经过明确设计。普通计数器不建议用这种隐式共享来规避 copylocks。