sync.mutex 不能直接放包变量里用，因为包初始化单 goroutine 执行，var mu sync.mutex 虽存在但无人调用 lock，若外部函数忘加锁则并发失效；必须封装进导出函数，禁止单独暴露 mu。
为什么 sync.Mutex 不能直接放包变量里用
包级互斥锁不是不能定义，而是“定义了却没效果”——因为 Go 的包初始化是单 goroutine 顺序执行的，init() 函数跑完后，var mu sync.Mutex 确实存在，但没人自动帮你调 mu.Lock()。真正并发访问时，如果所有函数都忘了加锁，它就只是个摆设。
常见错误现象：go run main.go 看不出问题，一上压测就数据错乱、计数不准、map panic；查半天发现是多个 goroutine 同时改了同一个包级 counter int，而 mu 根本没被调用。
- 必须把锁的使用逻辑封装进导出函数里，而不是暴露
mu给外部调用者自己决定锁不锁 - 不要在包变量里直接声明
var Mu sync.Mutex并期望别人记得Mu.Lock() - 如果真要暴露控制权（比如调试开关），至少用
atomic.Bool+ 注释警告：「修改此值需确保无并发写」
用 sync.Once 控制包级资源的首次初始化
包级并发控制最常踩的坑，是把“只该做一次”的事（比如加载配置、初始化连接池）放在普通函数里反复执行。这时候 sync.Once 比手写 if !inited { ... inited = true } 安全得多——它天然解决多 goroutine 同时触发初始化的竞争问题。
使用场景：全局 logger 初始化、数据库连接池 setup、feature flag 加载。
立即学习“go语言免费学习笔记（深入）”；
-
var once sync.Once必须是包级变量，且只声明一次 -
once.Do(func())内部不要调用可能阻塞或 panic 的逻辑，否则整个包卡死或不可恢复 - 别在
Do里返回错误；需要错误反馈的话，提前用sync.Once包一层初始化函数，把 error 存到包变量里
var (
db *sql.DB
initErr error
once sync.Once
)
func initDB() {
once.Do(func() {
db, initErr = sql.Open("mysql", "user:pass@/test")
})
}
包内多资源协同时，避免锁粒度粗暴升级为全局锁
一个包里有缓存、计数器、状态标志三个东西，很容易图省事全塞进一个 sync.RWMutex。结果是：读缓存要等写计数器完成，明明可以并行的操作被串行化，QPS 掉一半。
性能影响明显：压测时 pprof 显示 runtime.futex 占比飙升，mutex profile 里看到某把锁 hold 时间远超预期。
- 按访问模式拆锁：只读高频的（如配置 map）用
sync.RWMutex，读写低频的（如状态机）用普通sync.Mutex - 绝不把不同语义的字段塞进同一结构体再统一加锁——比如
type pkgState struct { Cache map[string]int; Counter int; Status string }就是危险信号 - 如果资源间真有强依赖（比如更新缓存前必须检查状态），优先用 channel 或状态机流转，而不是靠一把锁硬保序
测试包级并发逻辑时，go test -race 不是可选项
没开 race detector 就合并包级并发修改的代码，等于没测。Go 的竞态检测器能抓到绝大多数漏锁、误用 sync.Pool、非原子读写等低级但致命的问题。
容易忽略的点：测试文件里用 go func() { ... }() 启动 goroutine 时，主 goroutine 很可能在子 goroutine 执行完前就退出，导致测试“假通过”。
- 必须用
sync.WaitGroup或chan struct{}等待所有 goroutine 结束 - 测试中模拟高并发，别只起 2 个 goroutine ——
for i := 0; i 更容易暴露问题 - CI 流水线里强制加
-race，哪怕慢三倍；本地开发也养成go test -race ./... -count=1的习惯
真正难的不是写对第一版锁逻辑，而是后续有人加功能时，在新增函数里绕过原有锁机制、或在锁外读写了本该保护的数据。所以包级并发控制的边界，得靠函数签名和注释守住，而不是靠别人“应该知道要加锁”。
