sync.Map不是普通map的并发安全替代品，而是专为读多写少、键生命周期长场景设计的最终一致性结构，不支持for range、无len()、非原子遍历，频繁写入时性能更差。
别直接拿 sync.Map 替换你代码里所有 map —— 它不是通用解，用错场景反而更慢、更难 debug。
sync.Map 不是 map 的并发安全平替
它不支持 for range、没有 len()、不能用 m[key] 语法取值，Store/Load/Delete 全是方法调用。最关键是：它的设计目标很窄——「读多写少 + 键生命周期长」。比如缓存用户 session、只读为主的服务配置。如果你的业务要频繁增删 key（如 HTTP 请求 ID、临时任务 ID），sync.Map 内部的 dirty map 会频繁提升、miss 计数飙升，性能断崖下跌。
常见错误现象：
- 用
v, _ := m.Load("k")忽略ok，结果v是零值却误判 key 存在 - 在
Range回调里调用Store或Delete，干扰清理逻辑，甚至触发 panic - 以为
Range是原子快照，实际遍历时其他 goroutine 仍在改数据，看到的是一次弱一致性切片
Load/Store/Delete 的语义陷阱
sync.Map 对 nil 值不做区分：存 nil 和 key 不存在都返回 (nil, false)？不对——存 nil 时 ok 是 true，但值仍是 nil。所以永远要检查 ok，不能靠 v == nil 判断存在性。
立即学习“go语言免费学习笔记（深入）”；
参数差异明显：
-
Store(key, value interface{})：key/value 都是interface{}，无类型约束，运行时擦除 -
Load(key interface{}) (value interface{}, ok bool)：必须显式接收两个返回值 -
Delete(key interface{})：不返回是否删除成功，删不存在的 key 也不报错
性能影响：首次 Store 某个 key 会触发 dirty map 构建；后续写入若命中 read map 缺失，则走 double-check 路径，比普通加锁 map 更重。
Range 遍历为什么不能当 for range 用
它不实现 Go 的 range 协议，因为底层是分片哈希表 + 延迟清理，没有全局迭代器状态。每次 Range 调用都是独立快照，可能漏项、可能重复、无法保证顺序。
正确用法只有这一种：
m.Range(func(k, v interface{}) bool {
// 处理单个键值对
return true // 继续；false 中断
})
容易踩的坑：
- 在回调里调用
m.Load(k)—— 看似安全，实则可能让 entry 从read落到dirty，加速 miss - 想边遍历边删 key？不行。删操作不会反映在本次
Range中，且可能破坏内部状态 - 需要精确长度？只能自己在
Range里计数，没有m.Len()
什么时候该选 sync.RWMutex + map
多数真实业务更推荐这个组合：清晰、可控、基准测试常胜出。
适用场景：
- 读写都较频繁（比如统计指标、状态机映射）
- 需要
len()、delete()语义、或完整遍历保证 - key 类型固定、数量可预期，能用
make(map[K]V, hint)预分配 - 写操作本身不重（比如每秒几十次），锁粒度可控
sync.Map 的优势只在特定负载下成立：上万 goroutine 同时读，写极少，且 key 不频繁创建销毁。一旦偏离，它就从“优化”变成“包袱”。
真正容易被忽略的是：它的内部结构（read + dirty + miss）不是黑盒，而是有明确退化路径的——写多、key 短命、冲突高，都会让它悄悄变回加锁行为，还多一层间接成本。
