sync.Map 适合哪些键访问模式，何时普通 map 加锁更清晰

sync.Map 不是普通 map 的“更快并发版”。它最适合两类键访问模式：一个键写入一次、之后高频读取；多个 goroutine 分别读写互不相交的键。若代码需要编译期类型安全、频繁覆盖同一个键，或同时维护容量、计数器、多个键之间的规则，普通 map 配合 Mutex/RWMutex 往往更清晰。

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

生产目标：先保证状态规则清楚

选择并发映射时先问三个问题：一次业务操作只碰一个键吗？同一个键写入后是否基本不变？代码是否还要同步更新计数、淘汰链表或其他索引？前两个答案偏“是”时可以考虑 sync.Map；第三个答案为“是”时，显式临界区通常更容易审查。

环境准备：先识别键访问模式

Go 官方文档把 sync.Map 定义为专用类型，并直接建议大多数代码优先使用普通 map 加独立锁。它的优势不是“无锁”，而是内部实现针对特定访问分布做了优化。单个用户 ID 对应一个长期不变的客户端、插件名对应一次注册的处理器，属于写一次多次读；分片任务各自更新自己的键，属于互不相交键。

“读多写少”还不够精确：如果少量写入都集中在同一个热点键，或者读操作经常要遍历全表并与其他字段组合，sync.Map 的专用模式未必匹配。是否更快只能由实际负载基准回答，结构选择应先服从正确性。

安全配置：给 sync.Map 加类型化外壳

sync.Map 的键和值是 any。生产代码不要让类型断言散落在调用点，可用小包装把允许的键和值固定下来：

package registry

import "sync"

type Client struct {
    Name string
}

type Registry struct {
    items sync.Map
}

func (r *Registry) Load(id string) (*Client, bool) {
    // 只有本包装可以写入，类型断言边界集中在这里
    value, ok := r.items.Load(id)
    if !ok {
        return nil, false
    }
    return value.(*Client), true
}

func (r *Registry) LoadOrStore(id string, client *Client) (*Client, bool) {
    // loaded=true 表示返回的是已经存在的值
    actual, loaded := r.items.LoadOrStore(id, client)
    return actual.(*Client), loaded
}

func (r *Registry) Delete(id string) {
    // 删除只影响一个独立键，不附带全局计数规则
    r.items.Delete(id)
}

包装并不会让任意复合逻辑自动原子化。LoadOrStore 能原子决定“加载旧值还是保存给定值”，但如果调用前先构造昂贵对象，多个 goroutine 仍可能重复构造；它只避免重复发布，不保证构造函数只执行一次。

权限边界：整体不变量交给普通 map 加锁

缓存若同时维护总字节数，Put 操作就必须把“检查上限、替换旧值、更新计数”放在一个临界区。此时普通 map 更能表达规则：

package cache

import (
    "errors"
    "sync"
)

type Entry struct {
    Data []byte
}

type Cache struct {
    mu         sync.RWMutex
    items      map[string]Entry
    totalBytes int
    limitBytes int
}

func New(limit int) *Cache {
    // map 在构造阶段初始化，后续始终由 mu 保护
    return &Cache{items: make(map[string]Entry), limitBytes: limit}
}

func (c *Cache) Put(key string, entry Entry) error {
    c.mu.Lock()
    defer c.mu.Unlock()

    // 计算替换后的总量，保证 map 与计数器同时满足上限
    nextTotal := c.totalBytes + len(entry.Data)
    if old, ok := c.items[key]; ok {
        nextTotal -= len(old.Data)
    }
    if nextTotal > c.limitBytes {
        return errors.New("cache capacity exceeded")
    }

    c.items[key] = entry
    c.totalBytes = nextTotal
    return nil
}

func (c *Cache) Get(key string) (Entry, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()

    // 读取返回具体类型，不需要 any 断言
    entry, ok := c.items[key]
    return entry, ok
}

这段代码的重点不是 RWMutex 一定比 sync.Map 快，而是审查者能看到容量规则的完整原子边界。若还要维护 LRU 链表、租户配额、二级索引或删除回调，同一把锁可把相关状态放进一个可解释的事务。

日志审计：别把单次安全当成整体一致

sync.Map 的每个方法都可并发使用，但组合多个方法不自动形成事务。生产审计需要特别记录以下边界：

• Range 不对应一致快照；并发 Store/Delete 时，不同键可能反映不同时间点的值。
• 即使回调很快返回 false，Range 的复杂度仍可能是 O(N)，不能当成廉价“取第一个”。
• Load 返回的 ok 要单独判断，不能把不存在与保存的零值混为一谈。
• CompareAndSwap、CompareAndDelete 只约束一个键，不能维护跨键不变量。
• Clear 从 Go 1.23 提供，会删除全部条目；上线前要确认最低 Go 版本和调用权限。
• sync.Map 的零值可直接使用，但实例首次使用后不得复制；应通过指针嵌入服务对象。

发布检查：用竞态测试和真实基准做决定

上线前先用 go test -race ./... 覆盖并发读写、删除、重复注册和关闭路径；再按生产中的键数量、热点比例、读写比例和对象大小写 benchmark。只比较纳秒不足以决定结构，还要观察分配、尾延迟和代码复杂度。

# 先检查是否存在数据竞争
go test -race ./...

# 再运行包含真实键分布的基准，并记录分配
go test -run '^$' -bench 'MapAccess' -benchmem ./...

如果两种实现性能接近，优先普通 map 加锁：类型更明确，不变量更集中，故障分析也更直接。只有访问模式确实符合 sync.Map 的专用场景，并且基准显示锁竞争值得优化时，再承担它的 API 和快照边界。

常见问题

sync.Map 适合所有读多写少缓存吗？

不一定。它更明确地适合条目写一次后多次读取。若写操作集中在热点键、读取需要一致遍历或缓存伴随容量淘汰，普通 map 加锁可能更合适。

使用 RWMutex 是否一定比 Mutex 快？

不一定。读临界区短、写频繁或竞争较低时，Mutex 可能更简单。应先保证临界区正确，再用真实负载基准选择。

Range 里可以删除当前键吗？

可以调用其他 Map 方法，但遍历不是一致快照，结果不要用来生成必须精确对应某个时刻的账单、配额或审计报告。

结论

判断标准可以压缩成一句话：状态能否按独立键思考。写一次多次读、不同 goroutine 各管不同键时，sync.Map 值得考虑；一旦业务规则跨越同键的多个步骤、多个键或额外字段，普通 map 加 Mutex/RWMutex 更能把一致性边界写清楚。先选可证明正确的结构，再用竞态检测和基准决定是否需要专用优化。