Go Ristretto NumCounters 和 MaxCost 分别约束什么

Go Ristretto 的 NumCounters 和 MaxCost 都出现在 Config 里，但它们不是两种“缓存条目数量”。前者给 TinyLFU 访问频率统计准备空间，后者才是按照 Set 传入成本计算的缓存容量上限。调参时可以先记住一句话：NumCounters 影响“判断谁更常用”，MaxCost 约束“最多保留多少成本”。

官方地址：https://github.com/dgraph-io/ristretto/

一、先把两个参数放回 Ristretto 的工作模型

Ristretto 使用 TinyLFU 做接纳判断、SampledLFU 做淘汰判断。新值进入缓存前，系统需要知道候选 key 最近是否值得保留；这个判断依赖频率信息。真正把条目放进缓存后，又必须受一个容量预算约束。于是配置里同时出现了两笔预算：一笔是“观察访问行为”的统计预算，另一笔是“保存对象”的成本预算。

二、NumCounters 约束的是访问频率信息

NumCounters 表示要为多少个 key 保留访问频率信息。它服务于淘汰精度，不表示缓存最多有多少条数据。官方文档给出的经验是：如果缓存满载时预计保留 100 万个条目，可以把它设为约 1000 万，也就是条目数的 10 倍。内部还会向上取整到 2 的幂，因此实际统计空间可能略大。

例如，缓存里每个 value 都很小，但 key 种类很多，仍然要按“满载时的 key 数”估算，而不是按字节容量直接填写。设得过小，频率记录会更拥挤，TinyLFU 对冷热 key 的区分可能变粗；设得过大，则统计结构本身会多占内存，却不会把 MaxCost 提高。

config := &ristretto.Config[string, []byte]{
	// 按预计满载的 key 数量给频率统计留出余量，不是缓存条目上限。
	NumCounters: 10_000_000,
	// 所有 Set 的 cost 加总不能长期超过这个业务容量预算。
	MaxCost: 256 * 1024 * 1024,
	// 默认 64 通常足够，除非压测确认 Get 竞争明显。
	BufferItems: 64,
}

如果只想扩大缓存能保存的内容，不应该只改 NumCounters；如果只是想改善频率判断，也不应盲目扩大 MaxCost。这两个参数的内存代价和效果路径不同。

三、MaxCost 约束的是 Set 成本总量

MaxCost 的单位完全由应用自己定义，关键是它必须和每次 Set 的第三个参数保持一致。做字节缓存时可以把 cost 设成对象字节数；做数据库结果缓存时，也可以把 cost 设成估算行数、权重或固定等级。Ristretto 不会替你推断这些单位。

cache, err := ristretto.NewCache(config)
if err != nil {
	// 配置错误要在启动阶段返回，避免带着无效缓存继续提供服务。
	return err
}
defer cache.Close()

payload := []byte("cached response")
// 这里把字节数作为成本，MaxCost 也必须使用字节数。
accepted := cache.Set("user:42", payload, int64(len(payload)))
if !accepted {
	// false 只表示写入请求在缓冲阶段被丢弃，不等于已被淘汰。
	log.Println("cache set dropped")
}
cache.Wait() // 等待缓冲写入应用后再做需要一致观察的 Get。

即使 Set 返回 true，新条目仍可能在策略判断中不被接纳；这与 MaxCost 的容量限制是两件事。当前缓存成本接近上限时，新条目被接受后可能驱逐一个或多个旧条目。想改变运行中的成本上限，可以调用 UpdateMaxCost，但它仍然不改变 NumCounters 的统计规模。

四、用同一套成本模型检查配置

落地前先写下三个数字：满载时大约有多少个 key、单个 key 的成本如何计算、允许的总成本是多少。然后用下面的清单检查，避免把“条目数”“字节数”和“频率计数数”混在一起。

• 预计满载 100 万个 key：优先从约 1000 万个 NumCounters 起步，再用压测调整。
• 若 cost 是字节数：MaxCost 就写字节预算，不能写“条目数”。
• 若每个条目固定 cost=1：此时 MaxCost=100000 才近似表示 10 万条，但对象大小差异会被忽略。
• 命中率下降先看频率统计是否过小、cost 是否失真和 Set 是否被丢弃，不要只把 MaxCost 加倍。

常见问题

NumCounters 设成 MaxCost 可以吗？

数值上可以，语义上通常不合理。只有当两者恰好使用同一套“每条目固定成本”模型时，数值相同才有直观意义。

MaxCost 是 Go 堆内存的精确上限吗？

不是。它约束的是 Ristretto 看到的 cost 总量，运行时对象、key、统计结构和其他开销还会占用内存。

调整 NumCounters 会立即扩大缓存吗？

不会。它影响频率统计空间和接纳、淘汰判断精度；要改变容量，应调整 MaxCost 或每次 Set 的 cost 模型。