Go atomic.Uint64 的 Add 与 Load 如何组成统计快照

做并发指标时，经常只需要回答一个问题：到这一刻一共处理了多少次请求？如果多个 goroutine 同时增加计数，直接对普通 uint64 做 ++ 会产生数据竞争。sync/atomic 的 atomic.Uint64 可以把这个状态变成一个独立的原子计数器：写入端用 Add，读取端用 Load。

Add 原子地加上增量并返回加法完成后的新值，Load 原子地读取当前值。它们适合组成“单个指标”的统计快照；如果快照包含多个互相有关的字段，连续调用多个 Load 并不能自动得到同一时刻的整体状态。

先把 Add 和 Load 的职责分开

Add 解决的是并发写入的竞争：多个 goroutine 同时调用时，每次增量都不会因为读改写交错而丢失。它返回的是更新后的数值，所以可以直接作为本次请求的序号或采样点。Load 不改变计数器，只把当前存储的数值原子地取出来。

下面的例子只演示计数器的关系，不代表在文章环境中实际运行。读取端拿到的是某次 Load 发生时的单值快照，写入端仍可在下一刻继续增加。

package main

import (
    "fmt"
    "sync/atomic"
)

type Metrics struct {
    requests atomic.Uint64 // 零值为 0；首次使用后不要复制整个 Metrics
}

func (m *Metrics) recordRequest() uint64 {
    return m.requests.Add(1) // 原子累加，并返回递增后的新值
}

func (m *Metrics) snapshot() uint64 {
    return m.requests.Load() // 原子读取当前计数，不修改状态
}

func main() {
    var metrics Metrics
    current := metrics.recordRequest()
    fmt.Println("本次序号:", current)
    fmt.Println("当前总数:", metrics.snapshot())
}

一个计数器的快照，边界就是一次 Load

把 Load 的返回值记录下来，就得到了一个可打印、可上报或可用于阈值判断的单计数器快照。它不会锁住后续的 Add，因此适合低成本地采集请求量、重试次数、字节数等单一指标。

需要留意两个容易混淆的点。第一，Load 只保证这个计数器的原子读取，不会冻结其他字段。第二，Add 的增量类型是 uint64，长期累计时要评估溢出后的业务语义；如果计数允许回绕，阈值判断就不能只看简单的大小关系。

多字段统计不要把连续 Load 当成整体快照

假设结构里还有 errors 计数器，先读取 requests，再读取 errors 的过程中，另一个 goroutine 可能已经完成了一次请求并更新其中一个字段。两个数字都各自没有数据竞争，但它们未必来自同一时刻。

如果业务只需要独立指标，继续分别使用 atomic.Uint64 最简单。若页面必须展示“请求数、错误数、成功数”同一版本的组合，可以在写入侧构造新的不可变结构，再通过 atomic.Pointer 一次发布；或者用互斥锁把组合读写包起来。关键不是把所有字段都改成原子类型，而是先定义读者要的“一致”到底是单值一致，还是整组状态一致。

上线前检查这份小清单

• 统计对象中的 atomic.Uint64 是否在首次使用后被复制、按值返回或放入会复制的容器？官方文档明确要求首次使用后不要复制。
• 调用方是否把 Add 返回值误当成加法前的旧值？需要旧值时，不能用它替代 Swap 等语义不同的操作。
• 指标是否真的只有一个字段？如果要表达组合状态，先选择锁或原子发布整体对象。
• 计数是否可能接近 uint64 上限？提前约定回绕、截断或重置策略。

常见问题

atomic.Uint64 的零值能直接使用吗？

可以。它的零值就是 0，通常把它作为结构体字段声明即可；但首次使用后不要复制包含它的结构体。

Add 和 Load 之间需要自己加互斥锁吗？

对于这个计数器本身，不需要再包一层锁。若同一业务操作还要修改普通字段，仍要为那些字段建立明确的同步关系。

Load 读到的值会不会倒退？

在同一个原子计数器上，原子操作遵循 Go 的顺序一致语义；但如果把值跨进程、跨实例或经过异步上报链路比较，观察顺序还会受到外部传输过程影响。