Go atomic.Uint64 计数器溢出怎么办

日常开发用Go标准库的atomic.Uint64做请求计数、埋点累加这类场景时，遇到溢出本身不会直接报错，而是会自动回绕从0重新计数，根据你的业务场景选对应的处理方案就行。

atomic.Uint64溢出属于无符号整数的合法运算行为，不会触发Go运行时panic，不需要特殊处理的场景可以直接忽略回绕逻辑，对计数准确性有强要求的业务提前加阈值判断或者选用更大的计数存储类型即可。

Go 的 atomic.Uint64 适合做并发计数，但它仍然是一个固定宽度的无符号整数。计数达到最大值后，普通加法会按 64 位范围回绕到较小的数；原子性只能保证读写不互相撕裂，并不会替业务决定“溢出后应该怎么办”。如果指标不能突然回到 0，常见做法是用 CAS 实现饱和计数；如果业务需要长期累计，则应把计数按周期分段归档。

本文只讨论计数器溢出边界，不把它和多个字段组成的业务快照一致性混为一谈。

先分清回绕和并发访问

Uint64.Add 返回加法后的值。对无符号整数来说，超过可表示范围的部分会被截断，所以最大值再加 1 会变成 0。多个 goroutine 同时调用 Add 时，结果更新本身仍是原子的，但“结果不回绕”并不是默认保证。

排查时先看三件事：计数类型是否确实是 uint64，写入是否只经过 Add 或 CAS，业务是否把回绕后的较小值当成“服务恢复”。如果只是读取时偶尔出现较小值，不能立刻归因于并发读写撕裂，因为原子读取不会返回半个旧值和半个新值拼接出的数字。

用 CAS 做不会回退的饱和计数

如果指标的含义是“累计次数，达到上限后保持上限”，可以让更新逻辑在计算下一个值时先做边界判断，再用 CompareAndSwap 提交。CAS 失败说明别的 goroutine 先改了值，重新读取即可。

package counter

import "sync/atomic"

type SaturatingCounter struct {
	value atomic.Uint64 // 首次使用后不要复制这个结构体
}

func (c *SaturatingCounter) Add(delta uint64) uint64 {
	const maxUint64 = ^uint64(0) // 用位反取得 uint64 的最大值
	for {
		old := c.value.Load() // 原子读取当前计数
		if old == maxUint64 {
			return old // 已到上限，保持饱和状态
		}
		var next uint64
		if delta > maxUint64-old {
			next = maxUint64 // 加法会越界时改为限幅，而不是回绕
		} else {
			next = old + delta
		}
		if c.value.CompareAndSwap(old, next) {
			return next // 只有提交成功才返回本次更新结果
		}
		// CAS 失败表示并发写入发生，回到循环读取最新值
	}
}

func (c *SaturatingCounter) Load() uint64 {
	return c.value.Load() // 读取当前的饱和计数
}

这段代码把“并发安全”和“溢出策略”分成两层：Load 与 CAS 负责同步，maxUint64-old 负责判断是否还能相加。它不会把最大值误认为归零，但也不会替业务保存超过 64 位的真实累计量；如果必须精确记录更长周期，应把溢出前后的区间交给归档系统。

清零、分段和归档应该怎么选

Store(0) 会直接覆盖当前值，Swap(0) 会原子地写入 0 并返回旧值。它们解决的是“替换当前计数”，不是“让一个统计窗口在并发更新下自动闭合”。如果一个 goroutine 正在统计，另一个 goroutine 同时清零，清零前后的事件归属就需要由业务协议定义。

需要周期报表时，更稳妥的方案是把计数按分钟、请求批次或租户分段，让已封存的段只读；需要单个永不回退的监控值时，使用上面的饱和策略；需要精确总量时，使用数据库、日志或消息归档保存分段结果，不要把所有历史压力都塞进一个 Uint64。

遇到异常值时的排查清单

1. 确认异常值是否接近最大值后突然变小；这更像回绕，而不是普通并发读取问题。
2. 搜索所有写入点，区分 Add、Store、Swap 和 CAS，确认是否存在未约定的清零。
3. 核对指标采集端是否把无符号值转换成有符号值，避免展示层先发生截断。
4. 如果业务需要跨重启累计，检查归档或持久化链路；原子类型只负责进程内内存同步。

记住一个判断：atomic.Uint64 能让一次更新安全，但不会自动让计数无限增长。先确定溢出后的业务含义，再选择回绕、限幅或分段归档，问题就不会被误判成单纯的锁竞争。

相关问题

atomic.Uint64 能不能直接转换成 int64？

不建议把可能超过 int64 最大值的无符号计数直接转换后再展示。应先定义范围和溢出策略，再在边界内转换。

为什么不用互斥锁保护一个普通 uint64？

互斥锁也能实现正确同步，选择 atomic 还是锁应由更新模型、可读性和维护成本决定。atomic 只解决单个原子值的更新，不会自动保护相关字段。