Go race 检测器发现 map 竞态的最小复现

共享 map 只要出现并发读写，就应该先按数据竞态处理，而不是等运行时偶发崩溃。最小复现可以压缩成一个测试：主 goroutine 读取 map，子 goroutine 写入同一张 map，再用 go test -race 让检测器观察这条路径。修复时把读写统一放进 sync.RWMutex 的边界内，问题就从“散落在业务代码里的并发访问”变成了一个可以检查的对象。

先把竞态缩到一个共享 map

为了让报告容易阅读，先不要引入 HTTP、缓存或复杂业务。下面的结构只有一个共享 map、一个写入 goroutine 和一次读取。这里的输出是预期的检测结果示意，不把未执行的命令包装成真实运行截图。

package raceexample

import (
    "testing"
)

func TestSharedMapRace(t *testing.T) {
    values := make(map[string]int)
    ready := make(chan struct{})

    go func() {
        // 子 goroutine 写入共享 map；这里故意不加锁来保留竞态。
        values["orders"] = 1
        close(ready)
    }()

    // 等待写 goroutine 开始收尾，再读取同一 map；channel 只表达通知，不保护 map 访问。
    

这个版本的通知通道容易让人误以为已经同步。实际上，close(ready) 与接收操作只建立了通知前后的顺序；如果想表达“写入 map 已经完成”，仍需要确保读取发生在写入之后，并且所有后续并发访问都遵守同一同步协议。更直观的最小竞态通常把读取放进另一个 goroutine，使两条访问路径真正重叠：

func TestConcurrentMapReadWrite(t *testing.T) {
    values := make(map[string]int)
    start := make(chan struct{})
    done := make(chan struct{}, 2)

    go func() {
        // 让读写尽量同时进入，便于 -race 观察冲突。
        

go test -race 如何指出冲突位置

在包含测试文件的 module 目录执行下面的命令：

# -race 为测试二进制插入竞态检测；-count=1 避免复用成功缓存。
go test -race -count=1 ./...

预期现象是命令以非零状态结束，并在报告中分别列出 map 写入和 map 读取的调用栈。报告中的文件行号用于定位两条访问路径，不能理解为“某一行单独有问题”。Go 官方说明中，race detector 只检查被运行到的代码路径，因此一个没有跑到并发读写分支的测试即使通过，也不能证明整个程序无竞态。

还要区分两件事：map 本身的并发读写是不安全的，而竞态报告是检测器观察到的证据。某次运行没有报错，可能只是调度没有覆盖冲突窗口。可以通过重复测试、扩大并发场景或让测试接近真实工作负载来提高触发机会，但不要把重复次数当成同步手段。

用读写锁收拢修复边界

修复的重点不是在某个调用点临时加锁，而是让所有读写都经过同一组方法。读操作使用 RLock，写操作使用 Lock；返回值先在锁内取出，再释放锁，避免把受保护的 map 引用泄漏给调用方。

type Store struct {
    mu     sync.RWMutex
    values map[string]int
}

func (s *Store) Put(key string, value int) {
    s.mu.Lock()
    defer s.mu.Unlock() // 即使后续增加返回或错误分支，也能释放写锁。
    s.values[key] = value
}

func (s *Store) Get(key string) (int, bool) {
    s.mu.RLock()
    value, ok := s.values[key]
    s.mu.RUnlock() // 只把拷贝出的值带出锁边界。
    return value, ok
}

实际文件还需要导入 sync 并在构造时初始化 values。如果 map 的 value 是 slice、指针或可变结构，锁只保护 map 的查找和替换，不自动保护取出对象后的内部修改；这种情况下要么继续把对象的生命周期纳入锁，要么改成不可变快照。

最小复现的检查清单

相关问题

只读 map 也需要加锁吗？

多个 goroutine 同时只读通常不构成读写竞态，但只要生命周期中可能出现写入，就应把读取纳入统一访问协议，避免后来新增写路径时留下裸读。

为什么一次 go test -race 没有报告？

检测器是运行时工具，没有执行到冲突分支就没有观察对象。应补充能同时触发读写的测试场景，而不是单纯修改报告格式。

可以直接换成 sync.Map 吗？

只有当访问模式适合它的键值接口和语义时才考虑替换。普通 map 配合明确的读写锁更容易表达结构不变量，不能把容器替换当成通用竞态修复。