concurrency-safety

并发安全

何时用

• 写多线程、多协程、多进程代码，共享状态需要同步时。
• 异步任务（asyncio/goroutine/CompletableFuture/Task）有超时、取消或错误传播需求时。
• 发现压测下出现数据不一致、随机 panic、连接池耗尽等难以稳定复现的 bug 时。
• code review 发现锁的获取顺序不一致，或资源在异常路径下未释放时。

核心规则

1. 共享可变状态必须加保护，识别 check-then-act 竞态

规则： 所有被多个线程/协程读写的可变状态，必须用锁、原子操作或不可变数据结构保护；尤其要识别"先检查再操作"（check-then-act）这一最常见的竞态模式——检查和操作之间的窗口期可能被其他线程插入。

为什么： AI 生成并发代码时最常见的错误是：检查 if count < limit 后再递增——看起来没问题，但在高并发下两个线程可能同时通过检查，两个都执行递增，导致超出限制。还有"懒初始化"竞态：if instance is None: instance = ...，两个线程可能同时判断为 None 并各自创建一个实例。这类 bug 在低并发下压根不触发，在生产流量高峰时突然出现，且极难稳定复现。

怎么做：

// 反例：check-then-act 竞态（Go）
if counter < limit {        // ❌ 检查
    counter++               // ❌ 操作：两步之间有窗口，并发时超限
}

// 正例：用原子操作或锁合并 check 和 act
mu.Lock()
if counter < limit {
    counter++
    mu.Unlock()
    proceed()
} else {
    mu.Unlock()
    return ErrLimitExceeded
}
// 或者对于简单计数器，使用 sync/atomic
newVal := atomic.AddInt64(&counter, 1)
if newVal > limit {
    atomic.AddInt64(&counter, -1)  // 回退
    return ErrLimitExceeded
}

• 共享变量的读写要么全部在锁内，要么全部用原子类型（sync/atomic、std::atomic、Interlocked）。
• 不可变对象天然线程安全，优先设计成不可变：初始化后不修改，需要"修改"时创建新对象。
• 使用通道（channel）/消息传递代替共享状态时，明确通道的所有权（谁关闭、谁读、谁写）。

---

2. 锁粒度小、获取顺序一致，能用无锁结构优先

规则： 锁的粒度要尽量细（只锁需要保护的最小代码段），多个锁的获取顺序在整个代码库中必须一致；有线程安全的数据结构（sync.Map、ConcurrentHashMap、channel）可以替代手动锁时优先选用。

为什么： AI 生成代码时有两种相反的极端：一种是粗粒度地用一把大锁保护整个方法，锁持有时间过长，并发度接近零；另一种是在不同地方以不同顺序加多把锁——函数 A 先锁 X 再锁 Y，函数 B 先锁 Y 再锁 X，只要这两个函数同时在不同线程执行，就必然死锁。死锁在开发环境极难触发，因为并发度不够高，往往到压测或生产才暴露。

怎么做：

• 每个锁的用途和保护范围写在注释里：// mu 保护 cache 和 cacheExpiry。
• 多锁时建立全局获取顺序约定（如按锁的变量名字母序，或按资源层级：账户锁先于订单锁），文档化并通过 code review 强制执行。
• 锁内代码不做 IO（网络、磁盘）、不调用外部服务，否则锁持有时间不可控。
• 读多写少的场景用读写锁（sync.RWMutex、ReentrantReadWriteLock），提升并发读吞吐。
• 考虑无锁替代方案：原子操作、sync.Map、channel、CAS（Compare-And-Swap）。

---

3. 异步任务管理生命周期：超时、取消、异常传播

规则： 每个启动的异步任务都必须有：超时限制（防止无限挂起）、取消机制（支持优雅关闭）、异常传播路径（确保失败被感知）；禁止"发射后不管"的孤儿任务（fire-and-forget without error handling）。

为什么： AI 生成异步代码时极容易写出 asyncio.create_task(do_something()) 或 go func() { ... }() 然后不管——任务抛异常直接消失，日志里没有任何痕迹；任务永久挂起导致 goroutine 泄漏、协程泄漏；服务要关闭时孤儿任务还在运行，半途打断导致数据不一致。这类问题在轻载下毫无症状，在长时间运行后进程内存持续增长、协程数/线程数不断攀升，最终 OOM 或超时告警。