Go sync.Map.Clear 怎么一次清空并发映射

从 Go 1.23 开始，一次清空 sync.Map 不必再遍历删除，直接调用 m.Clear() 即可。官方定义很明确：它删除全部条目，使映射变为空；清空后的对象仍然可以继续执行 Store、Load 等操作。

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

标准库源码：https://go.dev/src/sync/map.go

最短答案：Go 1.23 及以上使用 cache.Clear()。但“Clear 能并发调用”与“清空后不会马上出现新数据”是两个问题；后者需要业务层协调写入。

Go 1.23 以上直接调用 Clear

下面的最小示例先写入两项数据，再一次清空，最后重新写入。sync.Map 的零值可以直接使用，因此无需构造函数。

package main

import (
    "fmt"
    "sync"
)

func main() {
    var cache sync.Map

    // 写入清空前的两条缓存数据。
    cache.Store("theme", "dark")
    cache.Store("region", "cn")

    // Go 1.23+：一次删除当前映射中的全部条目。
    cache.Clear()

    // 清空后读取旧键，loaded 应为 false。
    _, loaded := cache.Load("theme")
    fmt.Println("old key exists:", loaded)

    // 同一个 sync.Map 可以继续复用。
    cache.Store("theme", "light")
    value, _ := cache.Load("theme")
    fmt.Println("new value:", value)
}

如果编译器提示 cache.Clear undefined，先检查项目实际使用的 Go 工具链，而不是给 sync.Map 添加自定义方法。Clear 是 Go 1.23 新增 API，旧工具链无法识别。

做一个可重置的并发配置缓存

把调用放进一个小型类型，更接近真实项目。这里用配置缓存演示：多个 goroutine 可以读写不同键，配置源切换时调用 Reset 清掉旧值，然后按需重新加载。

package configcache

import "sync"

type Cache struct {
    values sync.Map
}

// Put 写入或覆盖一个配置项。
func (c *Cache) Put(key, value string) {
    c.values.Store(key, value)
}

// Get 读取配置，并把 any 收窄为 string。
func (c *Cache) Get(key string) (string, bool) {
    value, ok := c.values.Load(key)
    if !ok {
        return "", false
    }
    text, ok := value.(string)
    return text, ok
}

// Reset 删除当前缓存中的全部配置。
func (c *Cache) Reset() {
    c.values.Clear()
}

使用方只关心三件事：写入、读取和重置。清空后不需要重新分配 Cache，也不能把已经使用过的 sync.Map 按值复制给另一个变量；官方说明要求 Map 首次使用后不得复制。

package main

import (
    "fmt"

    "example.com/demo/configcache"
)

func main() {
    var cache configcache.Cache

    // 模拟第一批配置进入缓存。
    cache.Put("api_timeout", "3s")
    cache.Put("feature_x", "on")

    // 配置源换代时清空旧值。
    cache.Reset()

    // 重建后的数据仍写入同一个缓存对象。
    cache.Put("api_timeout", "5s")
    value, ok := cache.Get("api_timeout")
    fmt.Println(value, ok)
}

这个封装适合“缓存旧值全部失效，后续请求再填充”的场景。如果业务还要求类型安全、统计条目数，或必须让多个字段作为一个整体更新，普通 map[string]string 配合 sync.RWMutex 往往更清楚。官方也强调，sync.Map 是针对特定并发访问模式优化的专用类型，并非普通 map 的通用替代品。

理解并发安全不等于业务静止

sync.Map 的方法可以被多个 goroutine 并发调用，所以某个 goroutine 执行 Clear 时，其他 goroutine 调用 Load、Store 不会像普通 map 那样造成并发读写崩溃。不过，方法级安全并不承诺业务世界在清空期间停止变化。

例如，一个写入 goroutine 与 Clear 同时运行，清空返回后仍可能看到新条目。它可能是并发写入的结果，也可能是随后立即发生的新写入。这不表示 Clear 失效，而是说明“重置窗口内不得写入”属于更高层的不变量。

type ControlledCache struct {
    mu     sync.RWMutex
    values sync.Map
}

// Put 与 Reset 共用业务锁，避免重置窗口内并发写入。
func (c *ControlledCache) Put(key, value string) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    c.values.Store(key, value)
}

// Reset 独占业务锁，使清空与受控写入互斥。
func (c *ControlledCache) Reset() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.values.Clear()
}

这段代码的锁不是为了防止 sync.Map 数据竞争，而是为了表达业务规则。若读取也必须在重置期间停顿，Get 同样要持有读锁；若读取可以继续，则要定义它看到旧值或缺失值时的处理方式。

Go 1.22 及更早版本的兼容方案

旧版本没有 Clear。最直接的兼容写法是 Range 遍历键并逐个 Delete：

// clearCompat 用于没有 sync.Map.Clear 的旧 Go 工具链。
func clearCompat(values *sync.Map) {
    values.Range(func(key, _ any) bool {
        // 删除本次遍历观察到的键。
        values.Delete(key)
        return true
    })
}

这个方案可用，但需要接受三个边界：

• Range 可能是 O(N)，条目越多，遍历与删除工作越多。
• Range 不是映射内容的一致快照；并发修改时，它可能看到某个键在遍历期间的不同映射状态。
• 并发新增的键不保证被这一轮遍历删除，因此不能把它当作严格的“全局归零屏障”。

因此，兼容函数适合允许弱一致清理的缓存。若项目要求清理完成后所有请求立刻进入全新一代数据，应该改为“换映射”，而不是努力在旧映射上逐项删除。

需要整代替换时使用代际切换

代际切换的思路是：读写方总是先取得当前映射指针，重置方创建一个全新的空映射并原子替换指针。替换前已经取得旧指针的操作仍可能访问旧代，但替换后的新操作会进入新代，边界比逐项删除更容易描述。

package generationcache

import (
    "sync"
    "sync/atomic"
)

type Cache struct {
    current atomic.Pointer[sync.Map]
}

// New 创建第一代空映射。
func New() *Cache {
    c := &Cache{}
    c.current.Store(&sync.Map{})
    return c
}

// Put 总是写入调用开始时观察到的当前代。
func (c *Cache) Put(key, value string) {
    c.current.Load().Store(key, value)
}

// Get 从调用开始时观察到的当前代读取。
func (c *Cache) Get(key string) (string, bool) {
    value, ok := c.current.Load().Load(key)
    if !ok {
        return "", false
    }
    text, ok := value.(string)
    return text, ok
}

// Reset 原子发布一个全新的空映射。
func (c *Cache) Reset() {
    c.current.Store(&sync.Map{})
}

代际方案也有代价：已经持有旧指针的 goroutine 可能继续在旧代工作，旧代要等引用消失后由垃圾回收处理。若要求所有在途操作也必须停止，就仍然需要锁、版本校验或请求屏障，不能只靠换指针。

三种清空方案怎么选

常见问题

Clear 之后需要重新初始化 sync.Map 吗？

不需要。Clear 让当前映射变空，随后可以继续调用 Store 和 Load。不要通过按值赋值的方式“初始化”一个已经使用过的 sync.Map。

sync.Map 有 Len 可以确认已经清空吗？

没有内置 Len。在没有并发写入的受控测试中，可以用 Range 计数；在线并发环境里，遍历结果会随并发修改变化，不能把它当成瞬时一致的长度。

能不能用 cache = sync.Map{} 代替 Clear？

局部且未共享的变量可以在首次使用前赋零值，但共享后的 sync.Map 不应复制或随意替换变量本身。Go 1.23+ 优先调用 Clear；需要整代替换时，应显式管理指针并定义在途操作的语义。

Clear 适合所有缓存吗？

不一定。只写一次、读很多，或不同 goroutine 操作不同键时，sync.Map 更契合其设计目标。需要强类型、多字段事务式更新、精确条目统计或复杂不变量时，普通 map 加锁通常更容易维护。