256 分片并发 · 0 额外分配
比 golang-lru 快 4.2 倍

用分片代替排队

lru-next 把"一个全局锁的缓存"拆成 256 个独立分片，每把锁只覆盖 1/256 的数据——并发越高，收益越大。

同类对比

以下对比基于 Intel i5-8265U @ 1.60GHz · 10K key 固定池 · RunParallel 并发模式。

安装与使用

零外部依赖，仅使用 Go 标准库 + 泛型。

go get github.com/doc-war/lru-next

package main

import (
    "fmt"
    "time"
    "github.com/doc-war/lru-next"
)

func main() {
    // 创建一个最多缓存 ~1000 个 key、TTL 5 分钟的缓存实例
    c, err := cache.New[string](1000, 5*time.Minute)
    if err != nil {
        panic(err)
    }

    // 获取或通过 loader 回源加载
    val, err := c.GetOrLoad("hello", func(key string) (string, error) {
        return "world", nil
    })
    fmt.Println(val) // world

    fmt.Println(c.Len()) // 1
    c.Delete("hello")
    c.Clear()
}

核心概念

分片设计与快慢路径

256 分片 + 无锁 LRU + 双层检查，每层设计都为了一个目标：让最频繁的操作尽可能无锁。

路由与数据结构

GetOrLoad 快路径 / 慢路径

95% 以上的请求走快路径，仅加 RLock 即可返回。只有缓存过期或不存在时才走慢路径获取写锁。

算法组件

基准测试

硬件：Intel i5-8265U @ 1.60GHz, Windows, Go 1.25.3。10K key 固定池，RunParallel 并发模式，取 5 次均值。

并发写入（Load+Set / Add / Set）

并发读取（Get 命中）

* go-cache 无 LRU 淘汰，仅为 map + sync.RWMutex，功能不对等。

混合负载（90% 读 + 10% 写）

关键结论

• 写 & 混合场景全面领先分片设计大幅降低锁竞争，无锁 LRU 核心消除嵌套锁开销
• 相比 golang-lru v2（最流行 LRU 库）所有场景均有 2~4 倍性能优势
• 零额外分配Set 与 Get 操作均不产生堆内存分配

接口参考

// 创建一个最多缓存 maxKeys 个 key、TTL 为 ttl 的缓存实例
func New[T any](maxKeys int, ttl time.Duration) (*Cache[T], error)

// 获取或通过 loader 回源加载。loader 失败时返回旧过期值。
func (c *Cache[T]) GetOrLoad(id string, loader func(string) (T, error)) (T, error)

// 删除指定 key
func (c *Cache[T]) Delete(id string)

// 清空所有缓存
func (c *Cache[T]) Clear()

// 当前缓存条目总数（近似值）
func (c *Cache[T]) Len() int

错误处理

// GetOrLoad 在 loader 失败时的行为：
val, err := c.GetOrLoad("key", loader)

// ┌─ 缓存中无旧值 → 返回零值 + loader 错误
// ├─ 存在旧过期值 → 返回旧值 + loader 错误（降级模式）
// └─ loader 成功   → 返回新值 + nil

New 在 maxKeys 小于 1 时会自动提升为 1，保证缓存正常工作。

功能特性

• 泛型支持Cache[T any]，类型安全，无需类型断言
• 256 分片并发FNV-1a 哈希路由，单把锁只覆盖 1/256 的数据
• 无锁 LRU 核心lruCore 无自带锁，完全委托外层 RWMutex，零嵌套开销
• 缓存雪崩防护慢路径在分片锁内串行化 loader，天然 singleflight
• 脏数据优雅降级loader 失败时返回旧过期值，不中断服务
• 零外部依赖仅使用 Go 标准库，无第三方依赖
• 惰性过期TTL 在读取时检查，无后台定时器资源开销

已知限制

• 不支持持久化，纯内存缓存，重启后数据丢失
• 不支持分布式，单机缓存，各实例独立
• 不支持逐 key 单独 TTL，所有 key 共享同一过期时间
• key 仅支持 string 类型
• Len() 返回值为近似值，非精确计数
• 不支持通配符批量删除