Go 问答：atomic.Uint64 为什么不能复制已使用值：状态快照与并发计数边界

把并发计数器从一个函数传到另一个函数时，最容易踩的坑不是少加了一次，而是把已经使用过的 atomic.Uint64 按值复制了。复制后的对象看起来仍然能调用 Add，但它和原对象的状态、同步语义已经被拆开，go vet 也会把这类写法标成风险。

atomic.Uint64 可以被读取出一个数值快照，但不应该复制“已经使用过的原子值”本身；把它放进结构体后，优先传指针，初始化阶段完成复制，进入并发读写后只通过 Add、Load 和 Store 操作。

为什么“复制一个计数器”不等于读取当前值

假设服务想统计收到的请求数，最小模型可以写成一个结构体。这里真正共享的是 atomic.Uint64 这个对象，而不是某一时刻的数字。

package counter

import "sync/atomic"

type RequestStats struct {
	Total atomic.Uint64
}

func (s *RequestStats) Record() {
	s.Total.Add(1)
}

func (s *RequestStats) Snapshot() uint64 {
	return s.Total.Load()
}

Record 通过 Add 改变原子对象，Snapshot 通过 Load 取出一个当下可用的数值。后者返回 uint64，调用方拿到的是普通值，不会把 atomic.Uint64 一起复制出去。

按值传参会把同一个请求统计拆成两个对象

下面的写法看起来只是为了让函数签名短一点，实际却把包含原子字段的结构体复制了：

func recordOnce(s RequestStats) {
	s.Total.Add(1)
}

func badExample() {
	var stats RequestStats
	stats.Record()
	recordOnce(stats) // 复制已使用的 atomic.Uint64
}

recordOnce 修改的是复制出来的 Total。它并不会把同一次更新自动合并回 stats.Total。更麻烦的是，原子类型内部可能带有实现同步所需的状态，复制已使用值不是一种可以依赖的快照机制。

三种操作的边界要分开看

所以，想让辅助函数增加计数，应传指针：

func recordOnce(s *RequestStats) {
	s.Total.Add(1)
}

func safeExample() uint64 {
	var stats RequestStats
	recordOnce(&stats)
	return stats.Total.Load()
}

测试时可以直接检查 safeExample 返回 1。生产代码里则应确认 handler、定时任务和指标导出器都引用同一个 *RequestStats，不要在中间层无意中解引用后再按值传递。

用 go vet 把复制边界提前拦住

把示例保存后运行：

go vet ./...

如果复制发生在已经使用过的原子字段上，检查结果会指出复制位置。具体提示文本会随 Go 工具链版本略有差异，但排查方向很稳定：沿着调用参数、返回值、结构体赋值和切片追加，寻找包含 atomic.Uint64 的值复制。

这里别急着把所有结构体都改成全局变量。优先做两件事：一是把共享状态的边界收窄为 *RequestStats；二是只把 Load 的返回值交给日志、指标或响应层。

并发测试要验证“同一个对象”，不只验证最终数字

单线程返回 1 只能说明示例能跑，不能证明并发调用没有分裂计数器。可以让多个 goroutine 都持有同一个指针，最后检查 Load：

func TestRequestStats(t *testing.T) {
	var stats RequestStats
	var wg sync.WaitGroup
	for i := 0; i 

这段测试的关键不是数字够大，而是每次 recordOnce 都指向同一个 stats。再配合 go test -race ./...，能把普通数据竞争和原子对象误用分开观察。

常见问题

把 Load 的结果赋给另一个 uint64 会有风险吗？

不会。Load 返回的是普通数值快照，复制这个数值不会复制原子对象；但它也不会持续跟随原计数器变化。

结构体还没使用前可以按值返回吗？

初始化阶段规划好的零值结构体可以按值构造，但一旦其中的原子字段参与过读写，就不要再把它当普通值复制。团队里更稳妥的约定是从一开始就返回指针。

为什么不用互斥锁替代 atomic.Uint64？

如果计数器只是单个整数，原子操作更直接；如果更新时还要同时维护多个字段，就应把一致性边界放进互斥锁保护的临界区，别用多个独立原子操作拼出假原子事务。

提交前的检查清单

• 共享计数器是否以 *RequestStats 传递。
• 日志和指标层拿到的是 Load 返回值，而不是复制原子字段。
• go vet ./... 和 go test -race ./... 都已执行。
• 并发测试是否确认所有 goroutine 操作同一个 RequestStats。

把“原子值”理解成一个可随便复制的数字，是这个问题的根源。正确的分界是：对象负责同步，Load 负责给出快照，指针负责把更新汇聚到同一处。