Go atomic.Uint64 如何统计并发请求数

多个 goroutine 同时处理 HTTP 请求时，直接对普通 uint64 做 requests++ 不是可靠的统计方式：读、改、写并非一个不可分割的动作。更合适的做法是在共享服务对象里放一个 atomic.Uint64，每次完成请求调用 Add(1)，读取指标时调用 Load()。

核心结论：atomic.Uint64 的零值就是可用的零计数器；Add(1) 原子地累加并返回新值，Load() 原子地读取当前值。它只保护这个计数器，不会自动让其他字段组成一致快照。

先把并发计数器定义成共享状态

atomic.Uint64 位于 sync/atomic 包，适合表示只需要一个无符号整数的共享指标。它的零值是 0，因此服务创建时不必额外调用初始化函数。关键是把它放在共享对象中，而不是每次处理请求时临时创建：

package counter

import "sync/atomic"

// Service 持有一个进程内的请求计数器；所有请求共享同一实例。
type Service struct {
	requests atomic.Uint64
}

// NewService 依赖 atomic.Uint64 的零值，不需要手动初始化。
func NewService() *Service {
	return &Service{}
}

原子类型首次使用后不能复制。实际项目中不要按值返回已经运行过的 Service，也不要把 atomic.Uint64 放进会被复制的结构体切片里。通常让服务通过指针传递，就能把这条约束表达清楚。

每个请求用 Add(1) 累加并用 Load() 读取

请求处理完成后，把“完成一次请求”作为计数时机；如果产品定义的是“接收到请求”，则把调用放到入口处。Add 返回加法后的新值，适合在需要时记录本次请求对应的累计数：

package counter

import (
	"net/http"
	"strconv"
)

// ServeHTTP 演示请求完成后递增，并提供一个独立的查询接口。
func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// 真实业务应先完成处理；这里用 Add(1) 记录一次完成事件。
	newTotal := s.requests.Add(1)
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	w.WriteHeader(http.StatusOK)
	_, _ = w.Write([]byte("completed=" + strconv.FormatUint(newTotal, 10)))
}

// RequestCount 只读取计数器，不修改共享值。
func (s *Service) RequestCount() uint64 {
	return s.requests.Load()
}

示例中的 formatUint 代表项目自己的格式化函数，生产代码可以使用 strconv.FormatUint。如果只是给监控采集值，直接返回 uint64 更简单；不要为了返回旧值再做一次减一，因为那会制造额外的并发语义。

把计数与请求快照分开

原子计数器解决的是一个字段的并发读写。如果统计接口还要返回 lastPath、lastError 和时间窗口，那么一次 Load() 并不能让这些普通字段与请求数自动对应。可以将指标拆成独立的原子字段，或使用互斥锁保护一个完整快照：

// Snapshot 只在需要多个字段一致时使用锁保护。
type Snapshot struct {
	Total uint64
	Errors uint64
}

// 读取 Total 后再读取其他普通字段，不能声称得到了同一时刻的事务快照。
// 若业务要求强一致，应把字段放在同一个受保护的快照里统一读取。

工程上常见的选择是：请求总数、错误总数分别用原子类型；带有“总数 + 时间窗 + 最近错误”语义的管理页面，则在采样时复制一个受锁保护的快照。不要为了追求“无锁”而牺牲返回数据的含义。

错误与边界要在 API 层处理

首先记住返回值语义：Add(1) 返回递增后的值，Load() 返回读取时观察到的值。它们都不是数据库事务，也不会为请求计数提供跨进程持久化。uint64 达到最大值后会按无符号整数规则回绕；长期运行的总账应使用分段、落盘或外部指标系统。

此外，原子操作不能替代业务去重。如果同一请求因为重试被处理两次，计数器会忠实地加两次；要统计用户提交数、成功订单数等业务量，还需要在业务层定义幂等键和计数时机。

用旧版函数时怎样保持兼容

atomic.Uint64 是 Go 1.19 引入的类型封装。需要兼容更老的项目时，可以继续使用 atomic.AddUint64 和 atomic.LoadUint64 操作一个 uint64 地址，但最好集中封装成少数几个方法。新代码优先选择类型封装，因为字段本身更明确，也更不容易把普通读写混进来。

package counter

import "sync/atomic"

// 旧接口兼容层：所有访问仍然必须使用 atomic 包提供的操作。
type LegacyCounter struct {
	value uint64
}

// Inc 原子增加一次，并返回新的累计值。
func (c *LegacyCounter) Inc() uint64 {
	return atomic.AddUint64(&c.value, 1)
}

// Get 原子读取累计值；不要直接读取 c.value。
func (c *LegacyCounter) Get() uint64 {
	return atomic.LoadUint64(&c.value)
}

无论选哪种写法，原则只有一个：同一个共享字段的全部访问必须遵守同一套同步约定。Go 内存模型把 sync/atomic 的操作视为同步操作，并为原子操作提供顺序一致的观察顺序。

常见问题

atomic.Uint64 可以直接复制吗？

不能在首次使用后复制。把它放在指针指向的长期对象里，并避免按值传递包含它的对象。

Add(1) 返回旧值还是新值？

返回新值。如果调用方需要旧值，应重新设计接口，不要用减一模拟旧值。

Load() 能保证多个统计字段一致吗？

不能。它只原子读取当前这个 Uint64；多个字段需要共享锁、统一快照或分别接受独立采样语义。

什么时候应该使用互斥锁而不是 atomic.Uint64？

当更新动作涉及多个字段、需要条件判断后再修改，或需要把读取结果作为完整事务快照时，互斥锁通常更直接。