Go go vet copylocks 为什么提示复制 Mutex

运行 go vet 时看到 passes lock by value 或 copies lock value，通常不是编译错误，而是代码把包含 sync.Mutex 的结构体当成普通值传递了。最常见的入口是值接收者、值参数、值返回，以及遍历结构体切片时的 for _, item := range items。

处理原则很简单：Mutex 所在的对象一旦开始承担同步职责，就让调用链传递 *T，不要复制 T。下面按复制路径拆开看。

只要结构体已经包含并使用了 sync.Mutex，就不要让它以值接收者、值参数、值返回或 range 临时变量跨过业务边界；使用指针让同一个对象持有同一把锁。

go vet copylocks 到底在检查什么

go vet 的 copylocks 检查器会关注锁被按值传递的情况。Go 语言的结构体赋值是值复制；如果结构体里有 sync.Mutex，复制出来的值也带着一份锁相关状态，但它与原对象并不是同一把可协调的锁。

官方 sync.Mutex 文档给出的边界是“首次使用后不得复制”。因此，下面的类型定义本身没有问题，问题出在后续把 Cache 当值传来传去：

type Cache struct {
    mu    sync.Mutex
    items map[string]int
}

func (c Cache) Get(key string) int { // 值接收者会先复制整个 Cache
    c.mu.Lock()                     // 锁住的是副本，不是调用方持有的 mu
    defer c.mu.Unlock()             // 释放副本的锁，容易破坏同步意图
    return c.items[key]
}

这段代码可能仍然通过编译，但 go vet 会把“值接收者复制包含锁的类型”报告出来。警告的价值在于提前指出设计边界，而不是等并发问题出现后再猜是哪一把锁失效。

哪些写法会把 Mutex 复制出去

排查时先从签名和赋值点入手。除了值接收者，下面三类写法也很容易漏掉：

func snapshot(c Cache) Cache { // 值参数和返回值都复制 Cache
    return c
}

func readAll(items []Cache) int {
    total := 0
    for _, item := range items { // item 是每轮复制出的临时值
        total += item.Get("count")
    }
    return total
}

func clone(c Cache) Cache { // 不能用“复制后再清空 Mutex”补救
    return c
}

可以把检查点整理成一张表：

用指针接收者切断复制路径

最直接的修复是让方法在原对象上工作，并把函数参数也改成指针。这样复制的是指针值，锁仍然属于同一个 Cache：

func (c *Cache) Get(key string) int { // 指针接收者避免复制 Cache
    c.mu.Lock()                       // 保护原对象中的共享 map
    defer c.mu.Unlock()               // 无论返回路径如何都释放同一把锁
    return c.items[key]
}

func read(c *Cache, key string) int { // 参数传递指针，不复制 Mutex
    return c.Get(key)
}

func readAll(items []Cache) int {
    total := 0
    for i := range items { // 索引表达式可取到原切片元素的地址
        total += items[i].Get("count")
    }
    return total
}

如果确实需要导出数据，返回一个不带锁的快照，而不是返回整个 Cache。快照字段应在锁内读取后复制出去，例如返回 map 时还要决定是否需要复制 map 的内容，不能只复制一个可能共享底层数据的引用。

零值初始化安全，首次使用后复制不安全

声明一个尚未使用的 Cache，或者用字面量初始化业务字段，通常没有“复制已使用 Mutex”的问题；真正需要警惕的是对象已经参与过 Lock、Unlock 或其他同步操作后，又通过赋值、返回、参数或容器操作复制它。

不要用“复制后把新值重新初始化”来绕过提示。调用方很难证明所有复制发生在首次使用之前，而且这种写法会让对象的所有权和共享数据边界变得模糊。若业务确实要生成新对象，应明确构造新的 Cache，只迁移经过锁保护后读出的业务数据。

把 copylocks 放进提交前检查

先在模块根目录运行专门检查：

# 在整个模块中只检查按值传递锁的问题
go vet -copylocks ./...

# 继续运行默认检查，并把 copylocks 纳入同一次检查
go vet ./...

如果命令返回非零状态，先看报告指出的是接收者、参数、返回值还是 range 变量，再沿着调用链改成指针或无锁快照。go vet 使用启发式分析，不保证发现所有并发错误；它适合作为提交门禁的一部分，但不能替代竞态测试和代码审查。

常见问题

只有 Mutex 加过锁才会被 copylocks 提示吗？

不一定。检查器会根据类型和复制路径报告可疑的锁复制；即使当前调用看起来还没有并发，也应先修复对象的值语义。

把 Mutex 改成指针就能解决吗？

通常不应把 *sync.Mutex 当成通用替代品。更清晰的做法是让包含 Mutex 的业务对象使用 *T，由对象本身持有锁，并控制其生命周期。

返回结构体快照一定安全吗？

只有快照不再包含锁，并且其中的 map、slice 等引用数据已按需要复制时才安全。锁内读取和快照构造要作为一个完整边界设计。