Go atomic.Int64 和旧式原子函数怎么选择

如果项目已经使用 Go 1.19 或更高版本，新的整型共享状态通常优先写成 atomic.Int64；只有在必须兼容旧 Go 版本、已有接口明确要求 *int64，或需要最小改动维护旧代码时，才继续使用 atomic.AddInt64、atomic.LoadInt64 这一组函数。两者提供的原子语义并没有因为写法不同而改变，真正的差别在于类型边界、可读性和迁移成本。

官方文档：https://pkg.go.dev/sync/atomic

新写的结构体字段用 atomic.Int64，旧的独立 int64 地址接口先保留旧式函数；迁移时只改共享状态的所有访问点，不要把普通读写和原子读写混在一起。

类型化原子值和旧式函数分别暴露了什么

旧式 API 把地址作为参数，调用者要自己保证传入的是共享的 int64，例如 atomic.AddInt64(&total, 1)。这种形式对已有代码很友好，也便于给一个已经存在的字段加上原子操作，但裸字段仍可能被其他代码直接读取，维护时容易漏掉并发边界。

atomic.Int64 则把状态声明为一个原子值，调用点使用 counter.Add(1)、counter.Load() 或 counter.CompareAndSwap(old, next)。API 形状更接近普通对象方法，字段类型本身也在提醒读者：这里不能随意用 counter = counter + 1 代替原子更新。

迁移计数器时怎样保持调用语义不变

迁移时先把共享状态收拢到一个拥有者结构体里，再替换访问点。下面的封装保留了“增加并返回新值”和“读取当前值”这两个业务语义；调用方不需要知道底层是否从旧函数换成了类型化原子值。

package counter

import "sync/atomic"

// Stats 把并发计数器放在稳定的结构体地址中，避免散落的裸 int64。
type Stats struct {
	total atomic.Int64
}

// AddTotal 原子增加数量，并返回增加后的值。
func (s *Stats) AddTotal(delta int64) int64 {
	return s.total.Add(delta)
}

// Total 原子读取当前数量；调用者不直接接触共享字段。
func (s *Stats) Total() int64 {
	return s.total.Load()
}

// addLegacy 只在兼容 *int64 的旧边界时保留，避免扩散到业务层。
func addLegacy(total *int64, delta int64) int64 {
	return atomic.AddInt64(total, delta)
}

如果旧代码原来把 *int64 传给多个包，先保留一个很薄的适配函数会更稳妥。不要一边让新字段使用 atomic.Int64，一边让其他路径直接读取同一个普通副本；原子操作只保证这次原子访问，不会自动修复旁路读写。

迁移时最容易踩的两个边界

第一个边界是版本和布局。atomic.Int64 在 Go 1.19 引入，目标工程若仍需支持更早版本，就不能直接把它写进公共源码。Go 官方还特别说明，Int64 和 Uint64 在结构体及分配数据中会自动按 64 位边界对齐，这对 32 位目标比手动摆放普通整数更省心，但不代表整个项目的兼容性自动解决。

第二个边界是复制。atomic.Int64 的零值就是零，可以直接作为结构体字段使用；但它在首次使用后不能再复制。常见风险包括值接收者方法、把包含计数器的结构体按值传参，以及给结构体赋值生成副本。让方法使用指针接收者，并在需要传递时传结构体指针。

package counter

import "sync/atomic"

type Stats struct {
	total atomic.Int64 // 零值可用，但首次使用后不要复制 Stats。
}

// Snapshot 使用指针接收者，避免复制包含 atomic.Int64 的结构体。
func (s *Stats) Snapshot() int64 {
	return s.total.Load()
}

按项目约束做最后的 API 选择

可以把选择压缩成三问：项目最低 Go 版本是多少？共享字段是否可以收拢到一个稳定的拥有者结构体？现有边界是否已经固定为 *int64？前两问都支持类型化字段、且没有兼容负担时，用 atomic.Int64 更容易让后续代码保持一致；第三问为“是”时，旧式函数并不需要为了新而新。

无论选哪种写法，Load、Store、Add 或旧式对应函数都应覆盖这个共享状态的全部访问路径。若业务其实需要同时更新多个字段、维护复杂不变量，单个原子整数就不够了，应回到互斥锁或通过 channel 组织状态，而不是继续堆叠原子函数。

常见问题

atomic.Int64 能直接替换所有 atomic.AddInt64 吗？

不能直接替换。需要把字段从 int64 改成 atomic.Int64，再把传地址调用改成方法调用，同时确认项目最低 Go 版本和所有访问点。

atomic.Int64 的零值需要先 Store(0) 吗？

不需要。官方定义的零值就是零，直接作为结构体字段即可；只有业务需要从其他初始值开始时才调用 Store。

为什么包含 atomic.Int64 的结构体不能随便返回值？

首次使用后复制可能造成两个副本指向不同的内部状态，调用者容易误以为它们仍是同一个计数器。用指针接收者和指针传递可以避开这个问题。