Go sync.Map.Clear 清空并发缓存时怎么安排读写

我在给本地热点缓存做定时重置时，最容易误判的一点是：调用 sync.Map.Clear() 并不等于所有并发请求都在同一时刻停住。它的职责是删除当时 Map 中的全部条目；后续的 Load、Store 仍然可以继续发生。因此，简单地把“清空”和“回填”连成两行，只能解决旧条目残留，不能自动解决旧请求回写新一代缓存的问题。

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

先把 Clear 的边界说清楚

当前 Go 标准库文档把 Clear 定义为删除全部条目，使 Map 变为空。sync.Map 的读写操作可以被多个 goroutine 并发调用，但“安全并发访问”不代表业务流程拥有一个全局快照。

可以把重置想成一条时间线：请求 A 先 Load 到旧值，维护协程执行 Clear，请求 B 重新计算后执行 Store。A 如果在计算结束后无条件写回，就可能把旧一代结果覆盖到清空后的新一代中。相反，Clear 之后到来的 Store 也可能正常落入 Map；这不是 Clear 失效，而是调用顺序本来就允许交错。

最小重置配方：先清空，再按需回填

如果缓存值允许短暂未命中，最小方案可以直接调用 Clear，让下一次读取走回源逻辑。下面的示例把“读取”和“重置”分开，重置函数本身不假设所有读请求都已经结束。

package main

import "sync"

type Cache struct {
	items sync.Map // key 是业务键，value 是已经准备好的缓存值
}

func (c *Cache) Reset() {
	// Clear 只删除现有条目，不阻止其他 goroutine 继续 Load 或 Store。
	c.items.Clear()
}

func (c *Cache) Get(key string) (any, bool) {
	// ok=false 表示当前没有值，调用方应决定是否回源。
	return c.items.Load(key)
}

func (c *Cache) Put(key string, value any) {
	// 新一代数据可以在 Clear 前后正常写入，调用方需自行约束其来源。
	c.items.Store(key, value)
}

这个配方适合“旧值失效后允许重新计算”的缓存。它不适合要求所有请求同时切换、或回源结果必须严格属于同一批次的场景。后者需要把代际信息带入流程。

需要严格代际时，用版本号挡住旧回写

常见做法是维护一个原子代际号：重置时先递增代际，再 Clear；读请求记住开始时的代际，回源完成后只有在代际没有变化时才允许写入。这样即使旧请求跨过了 Clear，也不会把旧批次结果写回新批次。

package cache

import (
	"sync"
	"sync/atomic"
)

type GenerationCache struct {
	items sync.Map // key -> value，实际项目可把代际封装进 value
	gen   atomic.Uint64
}

func (c *GenerationCache) Reset() {
	// 先切换代际，让随后完成的旧请求发现自己已经过期。
	c.gen.Add(1)
	c.items.Clear()
}

func (c *GenerationCache) PutIfCurrent(key string, value any, started uint64) bool {
	// 只接受同一代结果，避免旧回源任务覆盖新缓存。
	if c.gen.Load() != started {
		return false
	}
	c.items.Store(key, value)
	return true
}

func (c *GenerationCache) Generation() uint64 {
	// 调用方在开始回源前保存这个代际号。
	return c.gen.Load()
}

这里的版本检查解决的是“旧请求回写”问题，不是把 Load 和 Store 变成一个事务。极端情况下，检查通过后到 Store 之间仍可能发生 Reset；若业务必须做到严格切换，应再用互斥锁或可替换的整体缓存对象保护切换点。

几个容易踩到的并发边界

生产代码里我会先回答一个问题：这个缓存是“允许短暂空窗”，还是“必须整批切换”？前者直接 Clear 更简单；后者应把 Reset 设计成一次有明确边界的业务操作，而不是依赖 Map 方法名来暗示一致性。

常见问题

Clear 会等待所有并发读请求结束吗？

不会。它清理 Map 的条目，但不会替调用方等待正在执行的回源逻辑或阻止新的 Load、Store。

Clear 之后马上 Store，值一定保留吗？

如果 Store 发生在 Clear 返回之后，它可以写入 Map；但要确认这个值是否属于当前业务代际。

用 Range 统计清空前后的数量可靠吗？

并发写入时不可靠。Range 不提供一致快照，统计结果只能作为近似观测，不能当作切换完成证明。

把 Clear 当成“删除条目”的原子动作，把代际号、锁或整体对象替换当成“业务切换”的控制手段，边界就清楚了。