sync.Mutex 复制后出现异常解锁的结构体设计

结构体一旦包含 sync.Mutex，它就不再适合像普通数据对象一样随意复制。最容易踩坑的写法是值接收者、值参数、结构体赋值和按值返回：这些操作同时复制了业务字段与锁的内部状态。后续一个对象执行 Lock，另一个副本却读取或修改同一份共享数据，锁与数据就失去了绑定关系。

解决办法很明确：让持有 Mutex 的对象以指针形式流转，方法使用指针接收者，构造后不要再按值复制；同时用 go vet 的 copylocks 检查把隐蔽的复制点提前暴露出来。

为什么按值传参会让 Mutex 和数据失去绑定

先看一个看起来很普通的计数器。调用 Add 时如果传入值，函数收到的是整个结构体副本；副本里既有 n，也有一份复制后的 mu。如果原对象和副本分别被不同的 goroutine 使用，它们各自加锁并不能互相排斥，哪怕两个方法都写着 Lock 和 Unlock。

package main

import "sync"

type Counter struct {
	mu sync.Mutex
	n  int
}

// Add 的值接收者会复制整个 Counter，也会复制其中的 Mutex。
// 这把锁保护的是副本的 n，不是调用方手里的原对象。
func (c Counter) Add(delta int) {
	c.mu.Lock()
	defer c.mu.Unlock() // 无论后续逻辑如何返回，都释放副本的锁
	c.n += delta
}

这里的危险不在于编译器不允许复制，而在于复制后的语义已经不再是“多个调用者共享一个受保护对象”。如果副本正好处在锁定状态，复制还可能让新对象带着不适合继续使用的内部状态，随后调用 Unlock 触发运行时错误。官方 sync 文档因此要求 Mutex 在首次使用后不得复制。

异常解锁通常是复制路径暴露出来的结果

“异常解锁”不一定只发生在显式 Unlock 上。更常见的是某个方法看起来已经加锁，但它拿到的其实是副本；另一个 goroutine 仍然操作原对象，于是数据竞争、计数错乱或锁状态错误会交替出现。下面这些位置都要重点排查：

注意，初始化阶段把一个尚未使用的零值结构体交给调用方，不等于允许之后随意复制它。稳妥的约定是构造函数从一开始就返回指针，并让类型的公共方法保持指针接收者。

把持锁对象改成指针，让 Unlock 回到同一对象

改造时不需要把 Mutex 改成指针字段。通常让 Mutex 作为结构体字段保留零值初始化能力，再让整个结构体通过指针传递即可。这样 Lock、业务字段和 Unlock 都针对同一个 *Counter。

package counter

import "sync"

type Counter struct {
	mu sync.Mutex
	n  int
}

// NewCounter 从创建开始就返回指针，避免调用方复制持锁对象。
func NewCounter() *Counter {
	return &Counter{}
}

// Add 使用指针接收者，让锁和 n 属于同一个 Counter。
func (c *Counter) Add(delta int) {
	c.mu.Lock()
	defer c.mu.Unlock() // 先建立释放责任，再更新受保护字段
	c.n += delta
}

// Value 读取同一个对象里的字段，返回普通数据而不是返回 Counter 副本。
func (c *Counter) Value() int {
	c.mu.Lock()
	defer c.mu.Unlock() // 读操作也要遵守同一把锁的保护范围
	return c.n
}

如果读取路径很多，可以根据实际模型改用 RLock，但不能因为“只是读”就把整个对象按值返回。若确实需要导出快照，应在锁内把普通字段复制到一个不含 Mutex 的快照类型，再返回快照。

type CounterSnapshot struct {
	N int
}

// Snapshot 只复制不含锁的结果，避免把同步原语带出对象边界。
func (c *Counter) Snapshot() CounterSnapshot {
	c.mu.Lock()
	defer c.mu.Unlock() // 快照读取和业务写入使用同一保护范围
	return CounterSnapshot{N: c.n}
}

用 go vet copylocks 把复制点提前找出来

完成指针改造后，可以把 go vet 放进本地检查或 CI。官方 vet 文档把 copylocks 定义为检查“锁被错误地按值传递”；它关注的是可疑复制路径，不是运行时并发证明。

# 在模块内检查可能按值传递锁的代码
go vet -copylocks ./...

看到值接收者、值参数、赋值或返回值相关提示时，先确认该类型是否真的包含 Mutex、RWMutex、Once、WaitGroup 等同步原语，再按对象边界改成指针或导出无锁快照。不要为了让检查安静而删除锁，也不要把锁单独指针化后继续复制外层对象。

还有三个容易漏掉的地方：不要把含锁结构体放进值类型的 range 变量中；不要用值类型切片做并发对象集合；不要用按值方法满足接口。接口接收的是值时，方法调用也可能在进入接口边界前发生复制。

相关问题

Mutex 还没 Lock 过时能不能复制？

零值初始化和首次使用后的复制是两个阶段。即使某次复制发生在第一次 Lock 之前，也不建议把它作为长期 API 约定；从构造函数返回指针更容易保持稳定的生命周期。

把 Mutex 改成 *sync.Mutex 能解决吗？

不一定。外层结构体仍可能被复制，多个副本可能共享同一把指针锁，也可能在初始化时各自得到不同的锁。优先让含锁对象整体以指针流转，并明确谁拥有锁和数据。

为什么 go vet 没报错，代码仍可能有并发问题？

copylocks 只针对它能静态识别到的复制路径；它不能证明所有共享数据都被同一把锁保护，也不能替代竞态检测、接口审查和生命周期设计。

把这类问题收束成一句设计规则即可：含有 sync.Mutex 的结构体不是普通值对象。让它从创建到调用都走指针边界，必要时只导出不带锁的快照，再用 go vet -copylocks ./... 把遗漏的按值路径提前暴露出来，异常解锁和“加锁却没保护住数据”的问题就会少很多。