Go map 并发读写为什么直接 panic

我在一个缓存索引里第一次遇到这个问题时，看到的不是普通的业务错误，而是运行时直接终止：fatal error: concurrent map read and map write。这类现象通常说明多个 goroutine 正在无同步地访问同一个普通 map，其中至少有一个访问会修改它。map 不是并发容器，偶尔不报错也不代表代码安全。

处理思路很明确：先把所有访问点找出来，再把 map 和同步手段封装在同一个边界内。读写都由同一把锁保护时，继续使用普通 map；读多写少且访问模式合适时再考虑 sync.Map；如果数据天然由一个 goroutine 所有，就用 channel 收口所有权。

官方资料：https://go.dev/ref/mem

我为什么把它当成架构问题处理

这个错误最容易被误判为“某一行赋值偶发失败”。实际上，问题在于 map 的内部状态由多个 goroutine 同时触达：一个 goroutine 可能在写入、扩容或搬移桶，另一个 goroutine 同时读取同一份结构。Go 运行时可以检测到部分冲突并直接停止程序，但没有检测到的时刻同样不能被当作安全窗口。

我会先把报错分成两类：concurrent map read and map write 表示读写交叉，concurrent map writes 表示多个写入交叉。它们都不是通过重试、加 sleep 或调整 goroutine 启动顺序能解决的业务异常，而是共享状态缺少同步边界。

最稳妥的修复是让 map 和锁一起拥有

如果业务仍然需要普通 map 的类型能力，最容易维护的做法是把 map 和 sync.RWMutex 放进一个结构体。读方法使用 RLock，写方法使用 Lock，解锁交给 defer，这样调用方没有机会绕过约定直接摸到内部 map。

package main

import "sync"

// SafeCache 把普通 map 的所有权和读写锁放在同一个边界内。
type SafeCache struct {
	mu   sync.RWMutex
	data map[string]string
}

// Get 只读取共享状态，因此使用读锁；返回值是字符串副本。
func (c *SafeCache) Get(key string) (string, bool) {
	c.mu.RLock()
	defer c.mu.RUnlock()
	value, ok := c.data[key]
	return value, ok
}

// Set 修改共享状态，必须使用写锁覆盖整个赋值操作。
func (c *SafeCache) Set(key, value string) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.data[key] = value
}

func NewSafeCache() *SafeCache {
	// 初始化 map，避免向 nil map 写入时产生另一个 panic。
	return &SafeCache{data: make(map[string]string)}
}

关键不在于“某个写操作前加一把锁”，而在于所有读、写、删除和遍历都要经过同一套封装。只给写入加锁、读取仍直接执行 cache.data[key]，或者把内部 map 返回给外部，仍然会留下并发读写路径。

什么时候考虑 sync.Map 或 channel

sync.Map 不是普通 map 的无脑替换。它适合键集合相对稳定、不同 goroutine 操作的键较少互相重叠，或者对象主要是写入一次、读取多次的场景。它的接口返回 any，类型断言和 API 语义也会改变，迁移前要确认这些代价。

如果数据有明确的单一拥有者，我更倾向于用 channel 传递请求，让一个 goroutine 独占普通 map。这样同步点从“每次 map 访问都加锁”变成“所有权只在一个执行者手里”，但调用方需要处理请求排队、退出和背压，不能只把 map 放进一个 channel 就算完成。

用 race 检测器确认是否还有漏网访问

修完后不要只观察“这次没有 panic”。我会用竞态检测器跑覆盖并发路径的测试：

# 用竞态检测器执行测试，优先覆盖读、写、删除和遍历路径。
go test -race ./...

它报告的是数据竞争，不等同于 map 运行时一定会抛出的 fatal error；反过来，一次测试没有报告也不代表所有未覆盖路径都安全。最终还要检查封装是否真的阻止了内部 map 泄漏、遍历是否持有合适的读锁，以及后台 goroutine 是否在退出时停止继续访问。

几个容易反复出现的误区

• 用 time.Sleep 调整时序：它只能改变复现概率，不能建立 happens-before 关系。
• 只锁写不锁读：读操作同样可能与扩容、删除或写入冲突。
• 把 map 复制一份就结束：如果复制过程本身发生在并发写入期间，复制动作也没有安全保证。
• 看到 sync.Map 就替换：容器类型变化会带来类型断言、遍历和生命周期语义的变化。

我现在的判断顺序是：先确认共享对象，再列出全部访问入口；能封装就优先普通 map 加锁；所有权清晰就考虑 channel；只有访问模式确实吻合时才选 sync.Map。这样修复的是共享状态的边界，而不是某一次碰巧触发的 panic。

相关问题

map 只有并发读取也需要加锁吗？

如果 map 在建立完成后完全不再修改，多个 goroutine 并发读取通常可以；但只要存在写入、删除、清空或可能发生的延迟初始化，就必须把这些状态变化纳入同步设计。

为什么加锁后还会出现同样的错误？

通常是有访问点绕过了封装，例如直接返回内部 map、对内部 map 做 range，或另一个后台任务保留了旧引用。应沿着所有读、写、删除和遍历路径继续查，而不是重复增加局部锁。