Go sync/atomic Uint64 对齐与无锁计数方案

Go 里做请求数、失败数、字节数统计时，sync/atomic.Uint64 是一条稳妥的无锁计数路径：把它作为结构体字段，通过指针接收者调用 Add 和 Load，不要在第一次使用后复制包含它的结构体。这样可以让类型自己处理 64 位对齐，避免把旧式 atomic.AddUint64 直接塞进可能未对齐的字段。

实践上的结论是：新代码优先选 atomic.Uint64；只有维护旧 API 或做极低层封装时，才需要手工审视 primitive 原子函数的地址对齐。计数器解决的是单个数值的并发读写，不会自动提供多字段快照一致性，也不等于一定比分片或互斥锁更快。

先看清 Uint64 的对齐责任

容易混淆的是两个名字相近的 API。atomic.AddUint64(&n, 1) 操作的是一个普通 uint64 地址，旧式 primitive 函数在 ARM、386 和 32 位 MIPS 上要求调用方安排 64 位对齐；Go 官方文档同时说明，atomic.Int64 和 atomic.Uint64 会自动对齐。

这意味着“字段类型是 uint64”不等于“它在所有目标架构上都适合拿给 primitive 原子函数”。一个前置的 32 位字段、嵌套结构体或手工切片偏移，都可能让地址布局变得不直观。不要靠当前机器是 amd64 这一点推断跨架构安全。

用 atomic.Uint64 封装一个可复用计数器

计数器只暴露业务真正需要的动作，内部字段保持私有。下面的结构体可以被多个 goroutine 共享，零值直接可用；方法使用指针接收者，既避免复制，也让调用意图更清楚。

package counter

import "sync/atomic"

// Counter 保存单调递增的事件数量，零值即可使用。
type Counter struct {
	value atomic.Uint64 // 类型内部负责 64 位原子值的对齐
}

// Add 记录 delta 个事件；调用方应保证 delta 是业务允许的增量。
func (c *Counter) Add(delta uint64) {
	c.value.Add(delta)
}

// Load 返回当前计数快照；它只保证这个字段自身的原子读取。
func (c *Counter) Load() uint64 {
	return c.value.Load()
}

// Snapshot 把计数器放进响应或日志前统一转换为普通值。
func (c *Counter) Snapshot() uint64 {
	return c.Load()
}

这里不需要 unsafe.Alignof，也不需要给前面加一个“看起来足够大”的填充字段。atomic.Uint64 的设计目标就是把低层对齐约束封装到类型里；读写路径则通过 Add、Load 维持原子性。

把 Add、Load 和快照边界写清楚

无锁计数最适合“事件发生一次就加一，读取时接受一个瞬时值”的指标。例如请求总数、重试次数和处理字节数，都可以用 Add 记录，管理接口或日志线程用 Load 读取。

尤其要留意“总请求数”和“失败请求数”一起读取的场景。两个 Load 都是原子的，但它们之间仍可能有新的请求完成，因此不能把两次读取拼成严格同一时刻的事务快照。若业务需要一组字段同时切换，应该把快照对象放在更高层用锁、不可变对象或专门的聚合策略保护。

复制、伪共享和分片是三个落地检查点

官方类型文档明确要求：atomic.Uint64 第一次使用后不能复制。不要把包含计数器的结构体按值返回、放进会被复制的值语义容器，或在赋值时制造第二份“同一个计数器”。构造后用指针传递，必要时把复制边界固定在初始化前。

第二个问题是伪共享。两个互不相关、却被不同 CPU 高频更新的原子字段如果落在同一缓存行，原子操作仍然正确，但缓存行会反复失效。可将热点计数拆成按 worker 分片的数组，每个 worker 只写自己的槽位，读取时再汇总；是否需要填充或分片，应以实际 profile 和压测结果决定，不要凭感觉填充。

第三个问题是争用。单个全局计数器的写入点越热，竞争越集中。可以用下面的决策顺序：

1. 只有一个数值、更新短且读多：先用一个 atomic.Uint64。
2. 多个 worker 高频写同一指标：考虑分片计数，读取时求和。
3. 需要多字段一致、条件更新或事务式重置：优先评估 sync.Mutex 或更高层聚合。

常见问题

普通 uint64 加上 atomic.AddUint64 就一定安全吗

不一定。64 位目标通常不容易暴露布局问题，但在 32 位 ARM、386 和 32 位 MIPS 上，primitive API 的调用方要保证 64 位对齐。新代码直接使用 atomic.Uint64 更稳妥。

atomic.Uint64 能保证多个统计字段同时一致吗

不能。它只保证自身的读写原子性；多个字段的组合快照仍需要锁、不可变快照或专门的聚合设计。

无锁计数一定比 Mutex 快吗

不一定。单字段、短路径上原子操作很合适，但高争用、伪共享或需要多字段一致时，分片或 Mutex 可能更易控、更符合业务语义。最终应看 profile 和压测。

落地时可以把检查清单压缩成四句话：新代码使用 atomic.Uint64；方法只接收指针；首次使用后不复制；超过单点热点后再按 worker 分片或提升到带一致性的聚合结构。