Go sync.Map.Range 中删除当前键会不会影响后续遍历

在缓存清理代码里，常见写法是让 sync.Map.Range 遍历条目，并在回调里直接删除已经过期的键。结论是：在 Range 回调中调用 Delete 是允许的，不会因为删除当前键而让 Range 本身失效；但这次遍历不是一致快照，不能把“本轮看到的键集合”当成某个时刻的完整库存。

官方资料：https://pkg.go.dev/sync#Map.Range

删除当前键可以做，遍历结果不能按快照理解。你需要先区分“并发访问是否安全”和“结果是否稳定完整”这两个问题。

先把 Range 的保证拆开

Range 会依次调用回调，回调返回 false 时停止。官方文档同时明确了三个边界：同一个键不会被访问多次；如果键的值在遍历期间被存储或删除，看到的映射可能来自 Range 调用期间的任意时刻；Range 不会阻塞 Map 的其他方法，回调自身也可以调用 Map 方法。

因此，“允许在回调里 Delete”描述的是调用关系，“不是一致快照”描述的是观察结果。前者解决死锁和并发 API 使用问题，后者决定了你能不能据此计算精确的总量、完整的过期清单或严格的分页边界。

删除当前键为什么不会让遍历失效

下面的代码适合“发现过期就尽快移除”这类清理动作。它不要求一次 Range 先复制出完整快照，也不把回调中的删除当成异常操作。

package main

import (
    "sync"
    "time"
)

type entry struct {
    expiresAt time.Time
}

func removeExpired(cache *sync.Map, now time.Time) {
    cache.Range(func(key, value any) bool {
        item, ok := value.(entry)
        if !ok {
            // 类型不符合预期时保留条目，避免清理逻辑误删数据。
            return true
        }
        if !item.expiresAt.After(now) {
            // Range 回调可以调用 Delete；这只删除当前判断到的键。
            cache.Delete(key)
        }
        // 返回 true 继续观察其他键，返回 false 则提前结束本轮。
        return true
    })
}

这里最重要的不是“后面的键一定不受影响”，而是不要为 Range 追加不存在的顺序保证。当前键不会因为已经被回调访问过而再次访问；但其他 goroutine 可能同时 Store、Delete 或覆盖值，所以后续回调拿到的是并发状态下允许出现的结果。

如果清理条件依赖值的最新版本，可以在删除前使用 CompareAndDelete 等带条件的操作，避免把另一个 goroutine 刚写入的新值误删。即使如此，整次 Range 仍然不是一致快照。

哪些需求不适合直接依赖这次遍历

以下需求要特别谨慎：统计“当前 Map 总共有多少条”、导出一份必须完整且互相一致的配置、按遍历结果生成不可重复的分页游标，以及要求所有过期键都在一次调用中被确认。Range 的文档语义并不承诺这些结果。

如果业务需要稳定观察边界，可以改用普通 map 配合 sync.RWMutex：在读锁或写锁覆盖的边界内完成快照，再在锁外处理删除。代价是锁竞争和更明确的生命周期管理。若场景只是高并发读写、条目各自独立，且清理允许分批进行，sync.Map 的弱快照语义通常更贴合目标。

发布前可以用这份清单复查

• 回调内 Delete 是否只是清理当前条目，而不是假设整个集合已经被冻结？
• 并发 Store 或覆盖值时，删除条件是否会误伤新值？
• 是否依赖遍历顺序、精确总量或“一次 Range 清完全部过期键”？
• 如果必须得到一致结果，是否应该换成普通 map 加显式锁？

一句话记忆：sync.Map.Range 允许回调调用 Delete，但它提供的是并发安全的遍历接口，不是冻结集合的快照接口。

相关问题

Range 返回 false 后还会继续调用回调吗？不会；当前回调返回 false 后，本次遍历停止。

删除当前键后，能否断言后续键一定按固定顺序出现？不能。Range 没有承诺稳定顺序，也不承诺与某个单一时刻的 Map 内容一致。