Go vet copylocks 如何发现锁复制风险

当一个结构体里放了 sync.Mutex、sync.RWMutex、sync.Once 或 sync.WaitGroup，它就不再适合像普通数据一样随意按值传递。go vet 的 copylocks 检查专门用来发现这类值复制路径：参数传递、返回值、赋值、切片或数组元素复制，以及部分循环变量使用。

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

修复的核心通常不是给锁加更多调用，而是让“拥有锁的对象”稳定地使用指针语义。需要注意，copylocks 是静态风险提示，不是数据竞争检测器；告警消失后仍然要审视共享对象的并发访问是否有正确的锁保护。

copylocks 到底在检查什么

官方 vet 文档把 copylocks 描述为“检查被错误地按值传递的锁”。它关注的是锁的内部状态可能随着结构体一起被复制，导致两个结构体看起来是两个对象，实际上携带了不应复制的同步状态。

例如，下面的 Counter 包含一个互斥锁。inc 的值接收者会先复制整个 Counter，然后才在副本上加锁：

package counter

import "sync"

type Counter struct {
	mu sync.Mutex // 锁保护 n，整个 Counter 不应再按值复制
	n  int
}

func (c Counter) inc() {
	c.mu.Lock()         // 这里锁住的是值接收者 c 的副本
	defer c.mu.Unlock() // 释放同一个副本里的锁
	c.n++
}

这个方法即使能够编译，也没有按预期修改调用方的计数器。更重要的是，调用方传入时已经发生了一次包含锁的复制。copylocks 的价值在于把“同步对象被当作普通值传递”的位置指出来，而不是替你判断整个业务是否存在竞态。

先从四类值传递位置读告警

排查时不要只盯着告警所在的那一行。沿着值的来源和去向看，通常可以归入四类：

下面的示例把后三种路径放在一起。它们是静态说明，不代表在当前机器上执行过；阅读重点是每个等号、返回值和 range 变量都会形成值语义：

func makeCounter() Counter {
	return Counter{} // 返回带锁结构体，调用方会按值接收
}

func copyCounter(original Counter) Counter {
	clone := original // 赋值复制了包含的锁
	return clone
}

func inspectAll(counters []Counter) {
	for _, c := range counters { // c 是当前元素的值副本
		_ = c.n
	}
}

运行 go vet ./... 时，默认检查集合会包含 copylocks。若只想把这个问题单独列出来，可以使用：

# 只运行锁复制检查，便于在修复并发结构时缩小噪声范围
go vet -copylocks ./...

输出中的文件名和行列位置是定位入口，不应机械地把每一条提示都改成指针。先确认这个类型是否代表一个“有身份的同步对象”，再决定修复方式。

优先把带锁对象改成指针语义

最小修复是让方法使用指针接收者，并让构造和调用链保留同一个对象：

func (c *Counter) Inc() {
	c.mu.Lock()         // 指针接收者不会复制 Counter 内部的锁
	defer c.mu.Unlock() // 退出方法时释放同一个对象的锁
	c.n++
}

func newCounter() *Counter {
	return &Counter{} // 返回对象地址，调用方共享同一个锁实例
}

func inspectPointers(counters []*Counter) {
	for _, c := range counters { // 这里复制的是指针，不是 Counter
		c.Inc()
	}
}

这里的关键不是“所有并发类型都必须用指针”这句口号，而是明确对象边界：*Counter 的复制只复制地址，多个调用者仍指向同一个 Counter；锁的归属也随对象保持稳定。对于需要独立计数器的场景，应分别创建多个 Counter，而不是复制一个已经使用过的对象。

自定义类型和“看起来像误报”的情况

copylocks 常见于标准库同步类型，但自定义结构也可能需要表达“不可复制”。Go 工具链里常用一个只用于静态分析的 noCopy 标记类型，让工具知道某个结构体一旦被使用就不应按值复制：

type noCopy struct{}

// Lock 和 Unlock 让 vet 把 noCopy 识别为不可复制的标记。
func (*noCopy) Lock()   {}
func (*noCopy) Unlock() {}

type Cache struct {
	_ noCopy       // 只表达复制约束，不承担运行时互斥
	mu sync.RWMutex // 真正保护 entries 的运行时锁
	entries map[string]string
}

这不是绕过检查的方法，也不会替你实现同步；它只把类型设计意图交给静态分析。实际项目中如果类型已经包含 sync.Mutex，通常不需要额外添加标记，直接统一指针接收者和指针容器即可。

遇到告警时可以按下面的顺序判断：

1. 这个值是否包含锁、Once、WaitGroup 或不可复制标记？如果只是普通 map、slice 或指针，问题可能属于另一类。
2. 复制发生在对象第一次使用之前，还是已经进入并发访问之后？不要把“现在恰好未加锁”当成稳定的 API 契约。
3. 调用方真正需要的是新对象，还是同一个有状态对象的别名？前者重新构造，后者传指针。
4. 修复为指针后，所有访问是否仍经过同一把锁？指针只解决对象身份，不会自动解决数据竞争。

把检查接到发布前的 Go 流程

在本地排查时可以先针对当前包运行，再扩大到整个模块；在持续集成中则建议固定使用整个模块的包集合：

# 先检查当前模块的全部包，发现值复制后再回到具体文件修复
go vet ./...

# 需要单独追踪锁复制变化时，只启用 copylocks 检查
go vet -copylocks ./...

go vet 使用启发式分析，退出成功不等于程序绝对没有并发问题；反过来，copylocks 的提示也不应通过忽略、改名或删除锁来消失。合并代码前至少确认三件事：带锁类型没有值接收者、集合保存的是指针或重新构造的独立对象、指针指向的共享字段仍由同一套锁保护。

几个容易混淆的问题

copylocks 能代替竞态检测吗？

不能。它主要发现“锁被复制”的静态路径，不能覆盖所有共享内存读写，也不判断锁的加解锁是否成对。需要结合代码审查和适合的并发测试工具。

把值接收者改成指针接收者就够了吗？

如果值还会在构造、返回、赋值或集合遍历处复制，单改一个方法仍可能留下告警。应从类型的创建入口到调用链一起检查。

指针复制会不会也有风险？

复制指针不会复制锁本身，但会让多个位置共享同一对象。因此它解决的是锁身份被复制的问题，访问规则仍要由锁、原子操作或其它同步协议保证。

为什么普通结构体复制没有 copylocks 提示？

copylocks 针对锁和不可复制同步状态。普通结构体可能有资源别名、深浅复制或业务状态问题，但那属于另一个设计检查范围。

记住一句话：copylocks 不是在要求所有结构体都用指针，而是在提醒你，包含同步状态的对象应先确定所有权，再决定如何传递。通常让它拥有稳定地址、使用指针接收者，并在 CI 中保留 go vet ./...，就能把这类风险尽早挡在合并之前。