cache

README

cache

通用的缓存接口

目前支持以下组件：

名称	包	状态
memory	内存
memcached	<github.com/bradfitz/gomemcache>
redis	<github.com/redis/go-redis>

// memory
c, _ := memory.New(...)
c.Set("number", 1)
var v int
c.Get("number",&v)
print(v)

// memcached
c = memcache.New("localhost:11211")
c.Set("number", 1)
c.Get("number", &v)
print(v)

n, setN, exists, err := c.Counter("n")
setN(-1) // 为 n 减 1
setN(10) // 为 n 加上 10

安装

go get github.com/issue9/cache

版权

本项目采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

Documentation

Overview

Package cache 统一的缓存系统接口

Index

• Constants
• func ErrCacheMiss() error
• func Get[T any](cache Cache, key string) (T, error)
• func GetOrInit[T any](cache Cache, key string, v *T, ttl time.Duration, init func() (T, error)) error
• type Cache
  • func Prefix(a Cache, p string) Cache
• type Cleanable
• type Driver
• type SetCounterFunc

Constants

const Forever = 0

Forever 永不过时

Functions

func ErrCacheMiss

func ErrCacheMiss() error

ErrCacheMiss 当不存在缓存项时返回的错误

func Get

func Get[T any](cache Cache, key string) (T, error)

Get cache.Get 的泛型版本

func GetOrInit

func GetOrInit[T any](cache Cache, key string, v *T, ttl time.Duration, init func() (T, error)) error

GetOrInit 获取缓存项

在缓存不存在时，会尝试调用 init 初始化，并调用 [Cache.Set] 存入缓存。

key 和 v 相当于调用 [Cache.Get] 的参数； 如果 [Cache.Get] 返回 ErrCacheMiss，那么将调用 init 方法初始化值并写入缓存， 最后再调用 [Cache.Get] 返回值。

Types

type Cache

type Cache interface {
	// Get 获取缓存项
	//
	// 当前不存在时，返回 [ErrCacheMiss] 错误。
	// key 为缓存项的唯一 ID；
	// v 为缓存写入的地址，应该始终为指针类型；
	Get(key string, v any) error

	// Set 设置或是添加缓存项
	//
	// key 表示保存该数据的唯一 ID；
	// val 表示保存的数据对象，如果是结构体，则会调用 gob 包进行序列化。
	// ttl 表示过了该时间，缓存项将被回收。如果该值为 [Forever]，该值永远不会回收。
	Set(key string, val any, ttl time.Duration) error

	// Delete 删除一个缓存项
	//
	// 如果该项目不存在，则返回 nil。
	Delete(string) error

	// Exists 判断一个缓存项是否存在
	Exists(string) bool

	// Touch 重新设置缓存项的过期时间
	//
	// 如果不存在该项，不会返回 [ErrCacheMiss]，而是 nil。
	Touch(key string, ttl time.Duration) error

	// Counter 从 key 指向的值初始化一个计数器操作接口
	//
	// key 表示计数器在缓存中的名称，如果已经存在同名值，将采用该值，否则初始化为零。
	// 如果 key 指定的值无法被当作数值操作，将在 f 的调用中返回相应在的错误。
	//
	// n 表示当前的数值；
	// f 表示对数据进行操作的函数；
	// exist 表示该元素原来是否就存在；
	Counter(key string, ttl time.Duration) (n uint64, f SetCounterFunc, exist bool, err error)
}

Cache 缓存内容的访问接口

func Prefix

func Prefix(a Cache, p string) Cache

Prefix 生成一个带有统一前缀名称的缓存访问对象

c := memory.New(...)
p := cache.Prefix(c, "prefix_")
p.Get("k1") // 相当于 c.Get("prefix_k1")

type Cleanable

type Cleanable interface {
	Cache

	// Clean 清除所有的缓存内容
	Clean() error
}

Cleanable 可清除所有缓存内容的接口

type Driver

type Driver interface {
	Cleanable

	// Ping 检测连接是否依然有效
	Ping() error

	// Close 关闭客户端
	Close() error

	// Driver 关联的底层驱动实例
	Driver() any
}

Driver 所有缓存驱动需要实现的接口

对于数据的序列化相关操作可直接调用 [caches.Marshal] 和 [caches.Unmarshal] 进行处理。 新的驱动可以采用 github.com/issue9/cache/cachetest 对接口进行测试，看是否符合要求。

type SetCounterFunc

type SetCounterFunc = func(n int) (uint64, error)

SetCounterFunc 为计数器增加数值的函数原型

n 为增加的数值，如果为负数，则表示减少。 返回的数值为操作完成之后的数值，如果数值被删除，则返回 ErrCacheMiss 错误。

调用此方法也会更新元素的 TTL 值。