golang支持泛型的带过期时间内存缓存插件库ttlcache的使用

TTLCache - 带项目过期和泛型的内存缓存

TTLCache是一个支持泛型的带过期时间的内存缓存库，具有以下特性：

• 简单API
• 类型参数
• 项目过期和自动删除
• 每次Get调用自动延长过期时间
• Loader接口可用于加载/懒初始化缺失的缓存项
• 线程安全
• 事件处理器(插入、更新和驱逐)
• 指标

安装

go get github.com/jellydator/ttlcache/v3

使用

基本用法

func main() {
    // 创建缓存实例，指定键类型为string，值类型为string
    cache := ttlcache.New[string, string]()
    
    // 插入数据
    cache.Set("key1", "value1", ttlcache.DefaultTTL) // 使用默认TTL
    cache.Set("key2", "value2", ttlcache.NoTTL)      // 永不过期
    cache.Set("key3", "value3", 10 * time.Minute)    // 自定义TTL
    
    // 获取数据
    if item := cache.Get("key1"); item != nil {
        fmt.Println(item.Value(), item.ExpiresAt())
    }
    
    // 检查键是否存在
    exists := cache.Has("key2")
    
    // 删除数据
    cache.Delete("key3")
    cache.DeleteExpired() // 删除所有过期项
    cache.DeleteAll()     // 删除所有项
}

自动过期删除

func main() {
    // 创建带TTL的缓存
    cache := ttlcache.New[string, string](
        ttlcache.WithTTL[string, string](30 * time.Minute),
    )

    // 启动自动过期项删除
    go cache.Start() 
    
    // 或者手动控制过期项删除
    for {
        time.Sleep(1 * time.Hour)
        cache.DeleteExpired()
    }
}

事件监听

func main() {
    cache := ttlcache.New[string, string](
        ttlcache.WithTTL[string, string](30 * time.Minute),
        ttlcache.WithCapacity[string, string](300), // 设置容量
    )

    // 插入事件
    cache.OnInsertion(func(ctx context.Context, item *ttlcache.Item[string, string]) {
        fmt.Println("插入:", item.Key(), item.Value())
    })
    
    // 更新事件
    cache.OnUpdate(func(ctx context.Context, item *ttlcache.Item[string, string]) {
        fmt.Println("更新:", item.Key(), item.Value())
    })
    
    // 驱逐事件
    cache.OnEviction(func(ctx context.Context, reason ttlcache.EvictionReason, item *ttlcache.Item[string, string]) {
        fmt.Printf("驱逐: %s (原因: %v)\n", item.Key(), reason)
    })
    
    cache.Set("event", "test", ttlcache.DefaultTTL)
    cache.DeleteAll()
}

自定义加载器

func main() {
    // 创建自定义加载器
    loader := ttlcache.LoaderFunc[string, string](
        func(c *ttlcache.Cache[string, string], key string) *ttlcache.Item[string, string] {
            // 模拟从数据库或其他来源加载数据
            value := "loaded-value-for-" + key
            return c.Set(key, value, ttlcache.DefaultTTL)
        },
    )
    
    // 创建带加载器的缓存
    cache := ttlcache.New[string, string](
        ttlcache.WithLoader[string, string](loader),
    )
    
    // 获取不存在的键会自动调用加载器
    item := cache.Get("some-key")
    fmt.Println(item.Value()) // 输出: loaded-value-for-some-key
}

限制缓存大小

func main() {
    // 创建带最大内存限制的缓存
    cache := ttlcache.New[string, string](
        ttlcache.WithMaxCost[string, string](5120, func(item ttlcache.CostItem[string, string]) uint64 {
            // 计算每个项的"成本"（这里简单使用键值长度之和）
            return uint64(len(item.Key()) + len(item.Value()))
        }),
    )
    
    // 添加数据
    cache.Set("large", strings.Repeat("a", 1024), ttlcache.DefaultTTL)
}

完整示例

package main

import (
	"context"
	"fmt"
	"time"
	
	"github.com/jellydator/ttlcache/v3"
)

func main() {
	// 创建缓存实例
	cache := ttlcache.New[string, string](
		ttlcache.WithTTL[string, string](30 * time.Minute),
		ttlcache.WithCapacity[string, string](100),
	)
	
	// 设置事件处理器
	cache.OnInsertion(func(ctx context.Context, item *ttlcache.Item[string, string]) {
		fmt.Printf("插入项: %s=%s (过期时间: %v)\n", 
			item.Key(), item.Value(), item.ExpiresAt())
	})
	
	cache.OnEviction(func(ctx context.Context, reason ttlcache.EvictionReason, item *ttlcache.Item[string, string]) {
		fmt.Printf("驱逐项: %s (原因: %v)\n", item.Key(), reason)
	})
	
	// 启动自动清理
	go cache.Start()
	defer cache.Stop()
	
	// 添加数据
	cache.Set("name", "张三", ttlcache.DefaultTTL)
	cache.Set("age", "30", 10 * time.Second) // 10秒后过期
	
	// 获取数据
	if item := cache.Get("name"); item != nil {
		fmt.Println("获取到name:", item.Value())
	}
	
	// 等待过期
	time.Sleep(11 * time.Second)
	if item := cache.Get("age"); item == nil {
		fmt.Println("age已过期")
	}
	
	// 使用加载器
	loader := ttlcache.LoaderFunc[string, string](
		func(c *ttlcache.Cache[string, string], key string) *ttlcache.Item[string, string] {
			return c.Set(key, "default-value", ttlcache.DefaultTTL)
		},
	)
	
	cache = ttlcache.New[string, string](
		ttlcache.WithLoader[string, string](loader),
	)
	
	fmt.Println("自动加载的值:", cache.Get("auto-loaded").Value())
}

这个库非常适合需要内存缓存且支持过期时间的场景，如API响应缓存、会话存储等。通过泛型支持，可以确保类型安全，同时提供了丰富的配置选项和事件机制。