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)

安装

go get github.com/issue9/cache

版权

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

Documentation

Overview

Package cache 统一的缓存系统接口

Index

• Constants
• func ErrCacheMiss() error
• type Cache
  • func Prefix(a Cache, p string) Cache
• type Cleanable
• type Counter
• type Driver
• type Serializer

Constants

const Forever = 0 //  永不过时

Functions

func ErrCacheMiss

func ErrCacheMiss() error

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

Types

type Cache

type Cache interface {
	// Get 获取缓存项
	//
	// 当前不存在时，返回 [ErrCacheMiss] 错误。
	// key 为缓存项的唯一 ID；
	// v 为缓存写入的地址，应该始终为指针类型；
	//
	// NOTE: 不能正确获取由 [Cache.Counter] 设置的值，[Cache.Counter]
	// 的实现是基于缓存系统原生的功能，存储方式与当前的实现可能是不同的。
	Get(key string, v any) error

	// Set 设置或是添加缓存项
	//
	// key 表示保存该数据的唯一 ID；
	// val 表示保存的数据对象，如果是结构体，需要所有的字段都是公开的或是实现了
	// [Serializer] 接口，否则在缓存过程中将失去这些非公开的字段。
	// ttl 表示过了该时间，缓存项将被回收。如果该值为 [Forever]，该值永远不会回收。
	Set(key string, val any, ttl time.Duration) error

	// Delete 删除一个缓存项
	Delete(string) error

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

	// Counter 返回计数器操作接口
	//
	// val 和 ttl 表示在该计数器不存在时，初始化的值以及回收时间。
	Counter(key string, val uint64, ttl time.Duration) Counter
}

Cache 缓存内容的访问接口

func Prefix

func Prefix(a Cache, p string) Cache

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

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

type Cleanable

type Cleanable interface {
	Cache

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

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

type Counter

type Counter interface {
	// Incr 增加计数并返回增加后的值
	Incr(uint64) (uint64, error)

	// Decr 减少数值并返回减少后的值
	Decr(uint64) (uint64, error)

	// Value 返回该计数器的当前值
	//
	// 如果出错将返回默认值。
	Value() (uint64, error)

	// Delete 删除当前的计数器
	//
	// 当计数器不存在时，不应该返回错误。
	Delete() error
}

Counter 计数器需要实现的接口

Cache 支持自定义的序列化接口，但是对于自增等纯数值操作， 各个缓存服务都实现自有的快捷操作，无法适用自定义的序列化。

由 Counter 设置的值，可能无法由 [Cache.Get] 读取到正确的值， 但是可以由 [Cache.Exists]、[Cache.Delete] 和 [Cache.Set] 进行相应的操作。

各个驱动对自增值的类型定义是不同的， 只有在 [0, math.MaxInt32] 范围内的数值是安全的。

type Driver

type Driver interface {
	Cleanable

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

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

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

对于数据的序列化相关操作可直接调用 [caches.Marshal] 和 [caches.Unmarshal] 进行处理，如果需要自行处理，需要对实现 Serializer 接口的数据进行处理。

新的驱动可以采用 github.com/issue9/cache/cachetest 对接口进行测试，看是否符合要求。

type Serializer

type Serializer interface {
	encoding.TextMarshaler
	encoding.TextUnmarshaler
}

Serializer 缓存系统存取数据时采用的序列化方法

如果你存储的对象实现了该接口，那么在存取数据时，会采用此方法将对象进行编解码。 否则会采用默认的方法进行编辑码。

实现 Serializer 可以拥有更高效的转换效率，以及一些默认行为不可实现的功能， 比如需要对拥有不可导出的字段进行编解码。