Go map 删除期间迭代怎样设计清理逻辑

我第一次把过期缓存清理写进服务时，直觉是先遍历 map，再在循环里删除过期键。真正让我停下来的是另一个问题：清理过程中如果又写入了新键，这个新键到底会不会被当前这一轮 range 处理？如果把这个问题当成“通常会”来写，清理结果就会悄悄依赖运行时的遍历选择。

更稳妥的做法是把契约拆开：对已经进入当前遍历视野的键，可以直接按条件删除；对遍历期间新建的键，不把它当作本轮必然处理的对象，必要时交给下一次清理。Go 规范明确说明 map 的迭代顺序不固定，尚未到达的键被删除后不会产生，而新建键本轮可能产生也可能跳过。

官方地址：https://go.dev/doc/

结论先说：单纯的“扫描并删除满足条件的旧键”可以直接写在 range 中；只要清理逻辑会新增键、依赖顺序或触发复杂副作用，就应把新增和清理拆成两个明确阶段。

先把清理任务分成三类对象

在云上做缓存、会话或临时索引清理时，我会先区分三类对象：本轮已经存在的键、扫描中被判定应该删除的键，以及扫描期间新产生的键。它们都在同一个 map 里，但不应该共享同一套“本轮一定处理”的假设。

可以把清理目标写成一个简单的不变量：如果某个键在判断时已经存在，并且满足过期条件，那么它可以被删除；如果某个键是在清理期间才写入的，就只承诺它会进入下一次可重复的清理范围。

range 中直接删除为什么成立

Go 的 delete 对 nil map 或不存在的键是空操作，因此删除动作本身不需要先做额外的存在性分支。更重要的是，规范对“尚未到达的 map 条目被删除”给出了明确语义：对应的迭代值不会再产生。这正好适合过期键清理。

// CleanupExpired 删除已经过期的条目。
// predicate 只负责判断，不在判断阶段修改 map。
func CleanupExpired[K comparable, V any](items map[K]V, expired func(K, V) bool) {
	for key, value := range items {
		// 先判断当前条目，再删除，不依赖 map 的遍历顺序。
		if expired(key, value) {
			delete(items, key)
		}
	}
}

这段写法的关键不在于“每轮都能访问所有键”，因为 map 的顺序本来就没有这种保证；关键在于每个已经被送进循环体的条目都能被独立判断。对于一次性过期清理，这个契约通常已经足够。

不要把新增键当成本轮必处理对象

我后来遇到的坑来自回调：清理某个旧键时，回调又往同一个 map 写入了一个刷新后的键。那时最容易写出一句未经证明的假设：“新键会在后面被 range 扫到”。规范并不承诺这一点，新建键本轮可能被产生，也可能被跳过，而且每个新建键的选择都可能不同。

因此，清理逻辑应该把“当前 map 的删除结果”和“下一轮应该处理的新输入”分开。若新增键必须立刻满足某个业务约束，就在写入时单独执行约束；不要把它是否被本轮 range 看到作为唯一保障。

// RefreshAndCleanup 先完成旧条目清理，再把新条目作为后续状态写回。
// 这样本轮是否看见 newKey 不会改变清理契约。
func RefreshAndCleanup(items map[string]int64, now int64, newKey string, newExpiry int64) {
	for key, expiry := range items {
		// 过期条目只从当前集合中移除。
		if expiry 

这里的“后续状态”不是说 Go 会自动开启下一轮，而是代码结构主动把新增写入放在清理循环之后。对于定时任务，下一次执行自然会再次检查它；对于请求内逻辑，则应明确写出新增键自己的有效期和校验规则。

副作用复杂时，先收集键再删除

直接删除适合判断简单、回调少的场景。如果每个过期键还要写审计、通知其他组件，或者删除动作会间接触碰同一个 map，我更愿意先收集键，再在第二段循环里执行删除。这样做不是为了改变 map 的遍历顺序，而是把“发现”和“变更”拆成两个可独立讨论的边界。

// CollectExpiredKeys 只读取 map，返回需要处理的键快照。
func CollectExpiredKeys(items map[string]int64, now int64) []string {
	keys := make([]string, 0)
	for key, expiry := range items {
		// 快照只保存键，不把 map 的遍历顺序带到业务层。
		if expiry 

这种方式的代价是多一个键切片，以及扫描和删除之间可能出现状态变化。如果 map 只由当前 goroutine 使用，这个取舍通常很清晰；如果它是共享状态，就必须把快照和删除放在合适的同步边界内，不能因为“先收集了键”就认为并发访问自然安全。

哪些做法会让清理结果变得不可控

我会特别避开下面三种写法。第一，在循环里根据上一个键推断下一个键的顺序；map 迭代顺序没有这样的承诺。第二，把新增键一定会在本轮被处理写成业务前提；它可能出现，也可能被跳过。第三，把复杂的新增、删除、通知和重试都塞进同一个回调；这会让清理边界难以复查。

上线前我会检查这份清理清单

最后我通常只问六个问题：过期条件是否是纯判断？删除是否只针对当前拿到的键？新增键是否有独立的写入约束？代码有没有依赖固定遍历顺序？副作用是否与扫描阶段分开？共享 map 是否由同一把锁或其他同步方案保护？如果这些问题都能回答清楚，range 中删除通常不需要被神秘化。

相关问题

Go map 在 range 中删除键会 panic 吗？

对同一个 map 的普通遍历删除，语言规范给出了明确边界；真正需要谨慎的是把删除与未定义的并发访问、复杂回调或顺序假设混在一起。

新增键本轮一定不会被遍历到吗？

不是。规范只说明它可能被产生，也可能被跳过，所以业务逻辑不能依赖其中任何一种结果。

nil map 可以直接 delete 吗？

可以，delete 对 nil map 是空操作；但给 nil map 赋值仍然需要先初始化，这属于写入边界。

对我来说，最实用的结论只有一句：把 map 清理当成“对已看到条目的条件删除”，把新增键当成“下一次状态”，代码就不会被随机遍历顺序绑架。