Map 实战陷阱：并发访问、迭代顺序与复合类型 Key
Go 的 map 很顺手：声明、索引、删除都只有一行。也正因为顺手，很多边界条件直到线上流量上来才暴露——缓存偶发崩溃、签名结果不稳定、计数把“不存在”和“值为零”混为一谈。
理解 map 不需要背运行时桶结构，但要守住语言层面的几条契约。
nil map 可以读，不能写
var counts map[string]int
fmt.Println(counts["go"]) // 0
delete(counts, "go") // 安全
counts["go"] = 1 // panic: assignment to entry in nil mapnil map 很适合表达只读的“当前没有任何条目”，但只要函数承担写入职责，就应在构造阶段初始化，而不是把检查散落在每次写入前。
type Counter struct {
values map[string]int
}
func NewCounter() *Counter {
return &Counter{values: make(map[string]int)}
}零值不等于不存在
单值索引会在 key 不存在时返回 value 类型的零值：
age := ages["alice"]如果 0 本身是合法值，必须使用 comma-ok：
age, exists := ages["alice"]
if !exists {
return ErrUserNotFound
}这不只是代码风格。权限、库存、限额等业务中，把“不存在”当成零值通常意味着绕过校验。
map 元素不可寻址
下面的代码无法编译：
type Stat struct {
Hits int
}
stats := map[string]Stat{"/": {}}
stats["/"].Hits++map 扩容时元素可能移动，因此语言不允许取得元素字段的稳定地址。解决方式有两种，各自表达不同的所有权：
// 值语义：取出、修改、写回。
stat := stats["/"]
stat.Hits++
stats["/"] = stat
// 指针语义：map 保存对象地址。
pointerStats := map[string]*Stat{"/": {}}
pointerStats["/"].Hits++指针写法不是天然更快。它增加了别名和 nil 的可能，也更容易把对象共享到多个 goroutine。选择依据应是“对象是否需要共享身份”，而不是少写两行代码。
遍历顺序不是随机 API
语言规范明确不保证 map 的迭代顺序。同一个进程中的两次遍历也可能不同。不要用遍历结果生成签名、缓存 key、SQL 参数快照或稳定测试输出。
需要稳定顺序时，先收集并排序 key：
keys := make([]string, 0, len(headers))
for key := range headers {
keys = append(keys, key)
}
slices.Sort(keys)
for _, key := range keys {
fmt.Println(key, headers[key])
}测试中更好的做法通常是比较结构，而不是比较打印后的字符串；只有协议确实要求顺序时才排序。
普通 map 不支持并发读写
多个 goroutine 只读且没有任何写入是安全的。一旦存在并发写，或者读写并发，就必须同步。运行时有时会直接报 concurrent map read and map write，但不能把这条报错当作检测器：没有崩溃不代表没有数据竞争。
最容易维护的方案通常是 map 与锁放进同一个类型，让调用方无法绕过锁：
type Sessions struct {
mu sync.RWMutex
data map[string]Session
}
func (s *Sessions) Get(id string) (Session, bool) {
s.mu.RLock()
defer s.mu.RUnlock()
value, ok := s.data[id]
return value, ok
}
func (s *Sessions) Put(id string, value Session) {
s.mu.Lock()
defer s.mu.Unlock()
s.data[id] = value
}不要返回内部 map，也不要返回调用方可以继续修改的可变引用，否则锁的保护范围会在函数返回时失效。需要快照时复制：
func (s *Sessions) Snapshot() map[string]Session {
s.mu.RLock()
defer s.mu.RUnlock()
return maps.Clone(s.data)
}什么时候使用 sync.Map
sync.Map 针对两类场景做了优化：条目通常只写一次、之后大量读取；或者不同 goroutine 操作彼此分离的 key 集合。一般业务状态优先使用带类型的 map[K]V + Mutex，因为不变量、类型和复合操作更容易表达。
“先 Load 再 Store”并不会自动变成原子业务操作。需要条件更新时，应使用 LoadOrStore、CompareAndSwap 等对应操作，或者回到锁内完成整个不变量检查。
Key 的设计比类型约束更重要
map key 必须可比较，因此 slice、map 和 function 不能直接作为 key。数组、字符串、整数、指针以及所有字段都可比较的 struct 可以。
复合 key 用 struct 通常比拼接字符串可靠：
type PriceKey struct {
TenantID string
SKU string
Currency string
}
prices := make(map[PriceKey]int64)字符串拼接容易遇到分隔符转义和字段顺序问题。struct 还能让编译器检查字段类型。
浮点数虽然可比较，却很少适合做业务 key。NaN != NaN，金额也不应使用浮点数表示；优先使用整数最小单位或明确的十进制定点类型。
make 的容量只是提示
make(map[K]V, n) 中的 n 是初始容量提示，不是上限，也不会一次性创建 n 个可直接观察的元素。能估算条目数量时提供提示可以减少扩容，但不要为了“防止增长”依赖它。真正的容量上限必须由业务逻辑维护。
删除和清空
delete 对不存在的 key 安全。需要清空整个 map 时，Go 1.21 起可以使用 clear(m)；也可以分配新 map。两者在别名语义上不同：
clear(m)会让所有持有该 map 的引用都看到空内容；m = make(map[K]V)只替换当前变量，其他引用仍指向旧 map。
这和切片一样，核心仍是所有权。