角色定位：你是一名 Go 工程师，将缓存视为一项系统设计决策。你会基于实测的访问模式选择逐出算法，依据工作集数据确定缓存容量，并始终为过期、加载器失败及监控做好规划。

在 Go 中使用 samber/hot 实现内存缓存

一款面向 Go 1.22+ 的泛型、类型安全的内存缓存库，支持 9 种逐出算法、TTL、带 singleflight 去重能力的加载器链、分片（sharding）、stale-while-revalidate 语义，以及 Prometheus 指标导出功能。

官方资源：

• pkg.go.dev/github.com/samber/hot
• github.com/samber/hot

本技能内容并非详尽无遗。更多细节请参考该库的文档与代码示例。Context7 可作为发现性平台提供辅助。

go get -u github.com/samber/hot

算法选型

请根据实际访问模式选择算法——错误的算法会浪费内存或显著降低命中率。

快速决策建议：默认从 hot.WTinyLFU 开始；仅当性能剖析显示未命中率超出服务等级目标（SLO）时，再考虑切换算法。

如需详细算法对比、基准测试结果与决策树，请参阅《Algorithm Guide》。

核心用法

带 TTL 的基础缓存

import "github.com/samber/hot"

cache := hot.NewHotCache[string, *User](hot.WTinyLFU, 10_000).
    WithTTL(5 * time.Minute).
    WithJanitor().
    Build()
defer cache.StopJanitor()

cache.Set("user:123", user)
cache.SetWithTTL("session:abc", session, 30*time.Minute)

value, found, err := cache.Get("user:123")

加载器模式（Read-Through）

加载器会在 key 缺失时自动拉取数据，并通过 singleflight 实现并发去重——对同一缺失 key 的多次 Get() 调用，仅触发一次加载器执行：

cache := hot.NewHotCache[int, *User](hot.WTinyLFU, 10_000).
    WithTTL(5 * time.Minute).
    WithLoaders(func(ids []int) (map[int]*User, error) {
        return db.GetUsersByIDs(ctx, ids) // 批量查询
    }).
    WithJanitor().
    Build()
defer cache.StopJanitor()

user, found, err := cache.Get(123) // 缺失时自动触发加载器

容量规划

设定缓存容量前，请先估算内存预算内可容纳多少条目：

1. 单条目大小估算：估算结构体本身大小，并加上堆分配字段（切片、映射、字符串）所占空间；同时计入 key 的大小。每条目约 100 字节的额外开销可覆盖内部簿记所需（指针、过期时间戳、算法元数据等）。
2. 向开发人员确认生产环境中为此缓存分配了多少内存（例如 256 MB、1 GB）。该值取决于服务整体内存配额及进程中其他组件的共享情况。
3. 计算容量：capacity = memoryBudget / estimatedItemSize，向下取整以预留余量。

示例：*User 结构体约 500 字节 + string 类型 key 约 50 字节 + 内部开销约 100 字节 = 每条目约 650 字节  
         256 MB 预算 → 256_000_000 / 650 ≈ 393,000 条目

若单条目大小未知，请让开发人员编写单元测试：批量创建 N 个实例并调用 runtime.ReadMemStats 进行实测。未经测量而盲目估算容量，极易导致 OOM 或内存浪费。

常见错误

1. 遗漏 WithJanitor()：若未启用清理器（janitor），过期条目将持续驻留内存，直至被逐出算法淘汰。务必在构建器中链式调用 .WithJanitor()，并在退出前 defer cache.StopJanitor()。
2. 未配置缺失缓存即调用 SetMissing()：运行时 panic。请先在构建器中启用 WithMissingCache(algorithm, capacity) 或 WithMissingSharedCache()。
3. 同时使用 WithoutLocking() 和 WithJanitor()：二者互斥，将 panic。WithoutLocking() 仅适用于单 goroutine 访问且无需后台清理的场景。
4. 缓存容量过大：缓存“全量存储”等价于一个带额外开销的 map。应按工作集大小设置容量（通常为总数据量的 10–20%），并通过命中率监控验证合理性。
5. 忽略加载器错误：加载失败时，Get() 返回 (zero, false, err)。务必检查 err，不可仅依赖 found 判断。

最佳实践

1. 始终设置 TTL —— 无界缓存将无限期提供陈旧数据，因缺乏刷新信号
2. 使用 WithJitter(lambda, upperBound) 分散过期时间 —— 若无 jitter，同批创建的条目将集中过期，引发加载器端的“惊群效应”（thundering herd）
3. 通过 WithPrometheusMetrics(cacheName) 启用监控 —— 命中率低于 80% 通常表明缓存容量不足或算法不匹配当前负载
4. 对可变值使用 WithCopyOnRead(fn) / WithCopyOnWrite(fn) —— 若不复制，调用方直接修改缓存对象将破坏共享状态

如需了解高级模式（再验证、分片、缺失缓存、监控集成等），请参阅《Production Patterns》。

如需完整 API 接口说明，请查阅《API Reference》。

若在使用 samber/hot 过程中遇到 bug 或非预期行为，请前往 https://github.com/samber/hot/issues 提交 issue。

交叉引用

• → 参考 samber/cc-skills-golang@golang-performance 技能，了解通用缓存策略，以及何时选用内存缓存、Redis 或 CDN
• → 参考 samber/cc-skills-golang@golang-observability 技能，了解 Prometheus 指标集成与监控方法
• → 参考 samber/cc-skills-golang@golang-database 技能，了解适配缓存加载器的数据库查询模式
• → 参考 samber/cc-skills@promql-cli 技能，学习如何通过 CLI 查询 Prometheus 缓存指标