cache

Gousing Cache

介绍

开箱即用的 Cache 工具，支持 Memory 和 Redis，统一的 API 快速设置及读取，支持 TAG 标签，支持全局默认过期时间，单 KEY 过期时间，提供 PluginDo 初始化回调插件(singleflight 防击穿) 和 PluginSet 泛型化集合插件……

安装及使用

go get gitee.com/gousing/cache
import  "gitee.com/gousing/cache"

全局默认缓存实例

	// 全局默认缓存实例，使用默认Store, 默认为 StoreMemory
	// Set使用全局默认过期时间
	cache.Set("key1", "StoreMemory")
	// SetExpire针对单个Key设置过期时间
	cache.SetExpire("key2", "valueExpire", time.Second)

	// 使用Memory实例
	cache.Store(cache.StoreMemory).Set("key1", "StoreMemory")
	// 或
	cache.Memory().Set("key1", "StoreMemory")
	// 使用Redis实例
	// 为了测试，清空Redis缓存
	cache.Redis().Clear()
	cache.Store(cache.StoreRedis).Set("key1", "StoreRedis")
	// 或
	cache.Redis().Set("key1", "StoreRedis")

	fmt.Println(`cache.Memory().Size()`, cache.Memory().Size()) // 2
	fmt.Println(`cache.Redis().Size()`, cache.Redis().Size())   // 1

	// 缓存读取
	fmt.Println(`cache.GetString("key1")`, cache.GetString("key1"))                                                   // "StoreMemory"
	fmt.Println(`cache.Store(cache.StoreMemory).GetString("key1")`, cache.Store(cache.StoreMemory).GetString("key1")) // "StoreMemory"
	fmt.Println(`cache.Store(cache.StoreRedis).GetString("key1")`, cache.Store(cache.StoreRedis).GetString("key1"))   // "StoreRedis"

	// TAG标签
	cache.Tags("tag1").Set("keyTag-1-1", 11)
	cache.Tags("tag1").Set("keyTag-1-2", 12)
	cache.Tags("tag2").Set("keyTag-2", 20)

	fmt.Println(`cache.Tags("tag1").Size()`, cache.Tags("tag1").Size()) // 2
	fmt.Println(`cache.Tags("tag2").Size()`, cache.Tags("tag2").Size()) // 1

	cache.Tags("tag1").Clear()                                          // Del tag1 all keys: keyTag-1-1,keyTag-1-2
	fmt.Println(`cache.Tags("tag1").Size()`, cache.Tags("tag1").Size()) // 0

	cache.Tags("tag2").Clear()                                          // Del tag2 all keys: keyTag-2
	fmt.Println(`cache.Tags("tag2").Size()`, cache.Tags("tag2").Size()) // 0


	// 自定义全局默认缓存仓库实例
	// 注意：请在项目初始化时进行自定义，仅需自定义一次，后续整个项目直接使用即可
	// SetDefaultStoreType 设置默认缓存仓库的驱动类型 StoreType
	cache.SetDefaultStoreType(cache.StoreType)
	// GetDefaultStoreType 获取默认缓存仓库的驱动类型 StoreType
	cache.GetDefaultStoreType() cache.StoreType 
	// GetDefault 获取默认缓存实例 StoreIO
	//   - 如果默认实例未配置(未初始化)，将自动尝试使用默认参数进行初始化
	//   - 用户可通过 `SetDefaultStoreType` 设置默认缓存实例的 StoreType 驱动类型(默认为 StoreMemory)
	//   - 用户可通过 `SetDefaultMemory` 设置自定义默认 StoreMemory 缓存实例
	//   - 用户可通过 `SetDefaultRedis` 设置自定义默认 StoreRedis 缓存实例
	cache.GetDefault() CacheIO
	// GetDefaultMemory 获取全局默认 StoreMemory 缓存实例
	//   - 用户可通过 `SetDefaultMemory` 设置自定义默认 StoreMemory 缓存实例
	//   - 如果默认实例未配置(未初始化)，会尝试使用默认参数自动延迟初始化
	cache.GetDefaultMemory() CacheIO 
	// SetDefaultMemory 设置全局默认StoreMemory缓存实例
	cache.SetDefaultMemory(io CacheIO) 
	// GetDefaultRedis 全局StoreRedis缓存
	//   - 用户可通过 `SetDefaultRedis` 设置自定义默认 StoreRedis 缓存实例
	//   - 如果默认实例未配置(未初始化)，会尝试使用默认参数自动延迟初始化
	cache.GetDefaultRedis() CacheIO
	// SetDefaultRedis 设置全局默认StoreRedis缓存实例
	cache.SetDefaultRedis(io CacheIO)

	// PluginDo 插件
	//   Key 缓存键名
	//   Do 缓存创建回调, 不存在或过期后回调创建缓存
	//   Read 读取缓存, 返回缓存值及错误
	//   Expire 可选, 过期时间 ( 默认为0, 表示使用缓存Store默认过期时间[无过期时间] )
	//   ForgetTime 可选, 缓存防击穿选项, 每个PluginDo实例可以自定义, 默认为 0，即singleflight默认方式。
	// 	 - singleflight 默认只能尝试一次，阻塞请求，直到执行完毕。
	//   - 如设置为 100ms, 表示100ms内的请求最多发起1次请求，每秒最大并发：10 RPS
	//   - 如设置为 200ms，表示200ms内的请求最多发起1次请求，每秒最大并发：5 RPS
	//   - 如设置为 500ms，表示500ms内的请求最多发起1次请求，每秒最大并发：2 RPS
	//   - 如设置为 1000ms，表示1000ms内的请求最多发起1次请求，每秒最大并发：1 RPS
		valRuning := 0
		doRuning := cache.PluginDo[int]().
			Key("usePluginDo").
			Do(func() (int, error) {
				valRuning++
				return valRuning, nil
			}).
			Expire(time.Second * 2)
		// 注意：IO将最小过期时间统一为 1s => time.Second
		// 注意：由于StoreMemory(FreeCache) 的过期时间是一个近似值，实际过期时间会在 (X-1, X] 秒之间，其中 X 是你设置的过期时间。
		// 我们测试的过期时间是 2s，所以实际过期时间会在 [1, 2] 秒之间，所以这里测试时，我们最多只能测试到 <2s 的过期时间。)
		var wg sync.WaitGroup
		wg.Add(11)
		// 未过期测试
		for range 10 {
			go func() {
				cerRuning, _:= doRuning.Read()
				fmt.Println(`未过期 cerRuning`,cerRuning)//1
				wg.Done()
			}()
		}
		// 已过期测试
		go func() {
			time.Sleep(time.Second*2 + time.Millisecond*100)
			cerRuning, _ := doRuning.Read()
			fmt.Println(`已过期 cerRuning`,cerRuning)//2
			wg.Done()
		}()
		wg.Wait()

	// 更多接口参见 IO Interface：
	// CacheIO interface
	// TagsIO interface

自定义实例

cache.NewMemory(options cache.MemoryOptions) (CacheIO,error)
memCache,err :=cache.NewMemory(cache.MemoryOptions{
	// CacheSize MemoryCache 占用内存大小, 单位MB,  默认 100M，最小10M
	//  - MemoryCache底层由freecache驱动, 每个freecache有256个segment，因此每个缓存[entry]大小不能超过 freecache内存大小的1/1024
	CacheSize: 256,
	// DefaultExpire 默认过期时间(配置单位为[秒]) 0 表示不过期(实例生命周期内/长久存储)
	DefaultExpire:0,
})
cache.NewRedis(options cache.RedisOptions) (CacheIO,error)
// RedisOptions Redis缓存配置信息
type RedisOptions struct {
	// Client Redis服务器链接选项，使用 UniversalClient 统一客户端，UniversalClient是对 Client 、 ClusterClient 、 FailoverClient 客户端的包装。
	// 	- 根据不同的选项，客户端的类型如下：
	// 	- 如果指定了 MasterName 选项，则返回 FailoverClient 哨兵客户端。
	// 	- 如果 Addrs 是 2 个以上的地址，则返回 ClusterClient 集群客户端。
	// 	- 其他情况，返回 Client 单节点客户端。
	//  - github.com/redis/go-redis/v9
	// 	- https://redis.uptrace.dev/zh/guide/universal.html
	// 	- RedisUniversalOptions is an alias for [redis.UniversalOptions]
	Client RedisUniversalOptions
	// DefaultExpire 默认过期时间(配置单位为[秒]) 0 表示不过期(实例生命周期内/长久存储) 注意：最小过期时间为1s time.Second
	// FreeCache 的过期时间是一个近似值，实际过期时间会在 (X-1, X] 秒之间，其中 X 是你设置的过期时间。
	DefaultExpire int
}
redisCache,err :=cache.NewRedis(cache.RedisOptions{
		// 单个主机或集群配置
		// 例如：[]string{"192.168.1.10:6379"}
		Client: cache.RedisUniversalOptions{Addrs: []string{"localhost:6379"}},
		DefaultExpire:0,
},0),

// 注意：IO将最小过期时间统一为 1s => time.Second
// 注意：由于StoreMemory(FreeCache) 的过期时间是一个近似值，实际过期时间会在 (X-1, X] 秒之间，其中 X 是你设置的过期时间。
// 我们测试的过期时间是 2s，所以实际过期时间会在 (1, 2] 秒之间，所以这里测试时，我们最多只能测试到 1s 的过期时间。)
memCache.Set("key1", "value1")
memCache.SetExpire("key2", "value2",time.Second)
memCache.GetString("key1") // "value1"
memCache.GetString("key2") // "value2"
time.Sleep(time.Second*2)
memCache.GetString("key1") // "value1"
memCache.GetString("key2") // ""

CacheIO 接口

type CacheIO interface {
	//Has 判断缓存是否存在
	Has(key string) bool
	//TTL 获取缓存过期时间 (返回0 表示不过期(实例生命周期内/长久存储) 注意：最小过期时间为1s time.Second)
	TTL(key string) (time.Duration, error)
	//Get 读取缓存
	Get(key string) (val []byte, err error)
	GetString(key string) string
	GetStringD(key string, defaultVal string) string
	GetInt(key string) int
	GetIntD(key string, defaultVal int) int
	GetInt8(key string) int8
	GetInt8D(key string, defaultVal int8) int8
	GetInt16(key string) int16
	GetInt16D(key string, defaultVal int16) int16
	GetInt32(key string) int32
	GetInt32D(key string, defaultVal int32) int32
	GetInt64(key string) int64
	GetInt64D(key string, defaultVal int64) int64
	GetUint(key string) uint
	GetUintD(key string, defaultVal uint) uint
	GetUint8(key string) uint8
	GetUint8D(key string, defaultVal uint8) uint8
	GetUint16(key string) uint16
	GetUint16D(key string, defaultVal uint16) uint16
	GetUint32(key string) uint32
	GetUint32D(key string, defaultVal uint32) uint32
	GetUint64(key string) uint64
	GetUint64D(key string, defaultVal uint64) uint64
	GetFloat32(key string) float32
	GetFloat32D(key string, defaultVal float32) float32
	GetFloat64(key string) float64
	GetFloat64D(key string, defaultVal float64) float64
	GetBool(key string) bool
	GetBoolD(key string, defaultVal bool) bool
	GetTime(key string) time.Time
	GetTimeD(key string, defaultVal time.Time) time.Time
	GetDuration(key string) time.Duration
	GetDurationD(key string, defaultVal time.Duration) time.Duration
	GetTimeMonth(key string) time.Month
	GetTimeMonthD(key string, defaultVal time.Month) time.Month
	GetTimeWeekday(key string) time.Weekday
	GetTimeWeekdayD(key string, defaultVal time.Weekday) time.Weekday
	GetIP(key string) net.IP
	GetIPD(key string, defaultVal net.IP) net.IP
	// Scan 方式获取缓存对象，适用于 Slice/Map/Struct 缓存对象, 反序列化扫描后放入引用地址变量
	Scan(key string, refVal any) error
	// Set 设置缓存（默认过期时间）
	Set(key string, val interface{}) error
	// SetExpire 设置缓存(标记过期时间,为0表示永不过期) , 注意：最小过期时间为 1s => time.Second
	SetExpire(key string, val interface{}, expire time.Duration) error
	// SetNotExist 设置缓存（标记过期时间,为0表示永不过期），不存在则设置
	SetNotExist(key string, val interface{}, expire time.Duration) error
	// ChangeInt 自增自减更新缓存(步进值为正数表示自增，步进值为负数表示自减) 标记过期时间,为0表示永不过期
	//   - expire 过期时间，如key存在则继续沿用原有过期时间，如key不存在则存储并设置过期时间
	ChangeInt(key string, step int, expire time.Duration) (newVal int, err error)
	// ChangeInt32 自增自减更新缓存(步进值为正数表示自增，步进值为负数表示自减) 标记过期时间,为0表示永不过期
	//   - expire 过期时间，如key存在则继续沿用原有过期时间，如key不存在则存储并设置过期时间
	ChangeInt32(key string, step int32, expire time.Duration) (newVal int32, err error)
	// ChangeInt64 自增自减更新缓存(步进值为正数表示自增，步进值为负数表示自减) 标记过期时间,为0表示永不过期
	//   - expire 过期时间，如key存在则继续沿用原有过期时间，如key不存在则存储并设置过期时间
	ChangeInt64(key string, step int64, expire time.Duration) (newVal int64, err error)
	// ChangeFloat32 自增自减更新缓存(步进值为正数表示自增，步进值为负数表示自减) 标记过期时间,为0表示永不过期
	//   - expire 过期时间，如key存在则继续沿用原有过期时间，如key不存在则存储并设置过期时间
	ChangeFloat32(key string, step float32, expire time.Duration) (newVal float32, err error)
	// ChangeFloat64 自增自减更新缓存(步进值为正数表示自增，步进值为负数表示自减) 标记过期时间,为0表示永不过期
	//   - expire 过期时间，如key存在则继续沿用原有过期时间，如key不存在则存储并设置过期时间
	ChangeFloat64(key string, step float64, expire time.Duration) (newVal float64, err error)

	//Del 删除缓存
	Del(keys ...string) error
	//Clear 清空全部缓存
	Clear() error
	//Size 获取已缓存数据的条目
	Size() int64
	//StoreType 获取缓存库的类型
	StoreType() StoreType
	//Tags 指定缓存标签
	Tags(tags ...string) TagsIO
	//Stats 获取性能指标统计信息
	Stats() StoreStats
}

type TagsIO interface {
	// Set 指定Tags下设置缓存（默认过期时间）
	Set(key string, val interface{}) error
	// SetExpire 指定Tags下设置缓存(标记过期时间,为0表示永不过期)
	SetExpire(key string, val interface{}, expire time.Duration) error
	// SetNotExist 指定Tags下设置缓存（标记过期时间,为0表示永不过期），不存在则设置
	SetNotExist(key string, val interface{}, expire time.Duration) error
	//Del 删除指定Tags下的缓存
	Del(keys ...string) error
	//Clear 清空指定Tags下的全部缓存
	Clear() error
	//Size 获取指定Tags下缓存数据的条目
	Size() int64
}

Gousing 通用选项

自定义 Logger

// Cache 日志默认使用Golang标准库slog.Default()全局日志记录日志
// cache.SetLogger(*slog.Logger)
myLogger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
cache.SetLogger(myLogger)

自定义 Jsoner

// Cache 序列化默认使用兼容标准库的json-iterator
// jsoniter.ConfigCompatibleWithStandardLibrary
type JsonerAPI interface {
	// Marshal adapts to json/encoding Marshal API
	// Refer to https://godoc.org/encoding/json#Marshal for more information
	Marshal(v any) ([]byte, error)
	// Unmarshal adapts to json/encoding Unmarshal API
	// Refer to https://godoc.org/encoding/json#Unmarshal for more information
	Unmarshal(data []byte, v any) error
	// Valid reports whether data is a valid JSON encoding
	Valid(v []byte) bool
}

// SetJsoner 自定义 Json 操作库，为nil则不设置
var myJsonerApi JsonerAPI
cache.SetJsoner(myJsonerApi)
// UseStandardLibrary 切换Json库为 Json StandardLibrary 标准库
cache.UseStandardLibrary() 
// UseJsonIterator 切换Json库为 Json Iterator 库
cache.UseJsonIterator() 

感谢

1. Cache Memory 使用 freecache 驱动 github.com/coocood/freecache
2. Cache Redis 使用 go-redis(v9) 驱动 github.com/redis/go-redis

Benchmark

统一便捷的 IO 接口封装后性能损失极低：

goos: windows
goarch: amd64
pkg: gitee.com/gousing/cache
cpu: 12th Gen Intel(R) Core(TM) i5-12400F
go.exe test -benchmem -benchtime=100000x -run=^$ -bench ^Benchmark gitee.com/gousing/cache

Benchmark Memory

Benchmark Redis

Benchmark Plugin