cache

Documentation

Index

• Constants
• Variables
• type Cache
  • func (c *Cache) AddLocalCache(key Keyer) error
  • func (c *Cache) Get(key Keyer) (interface{}, error)
  • func (c *Cache) Init(ptr interface{})
  • func (c *Cache) IsHotKey(key Keyer) bool
  • func (c *Cache) Remove(key Keyer) error
  • func (c *Cache) Update(key Keyer, oper interface{}) (interface{}, error)
• type CacheCallback
• type CacheErrCallback
• type Cacher
  • func NewLocalCacher(prefix string, max int) Cacher
  • func NewRedisClusterCacher(prefix string, opts *redis.ClusterOptions) Cacher
  • func NewRedisSingleCacher(prefix string, opts *redis.Options) Cacher
• type Database
• type Keyer
• type LocalCacher
  • func (c *LocalCacher) Del(key Keyer) error
  • func (c *LocalCacher) Get(key Keyer) ([]byte, error)
  • func (c *LocalCacher) Set(key Keyer, data []byte, ttl time.Duration) error
• type Locker
• type RedisCacher
  • func (r *RedisCacher) Del(key Keyer) error
  • func (r *RedisCacher) Get(key Keyer) ([]byte, error)
  • func (r *RedisCacher) Set(key Keyer, data []byte, ttl time.Duration) error
• type TypeNotMatchErr
  • func (t *TypeNotMatchErr) Error() string

Constants

const (
	UpdateActionSet = 1
	UpdateActionDel = 2
)

const (
	CacheTypeLocal  = 1
	CacheTypeRemote = 2
)

const EnumDefault = 0

Variables

var (
	ErrNotFound  = errors.New("not found")
	ErrCacheMiss = errors.New("cache miss")

	ErrDeadlineExceeded = errors.New("dead line exceeded")

	ErrLockTimeout = errors.New("acquire lock timeout")
)

Types

type Cache

type Cache struct {

	// 远程cache实体
	RemoteCache Cacher
	// 远程cache缓存TTL
	RemoteTTL time.Duration
	// 当调用Get的时候，远程cache命中了，会回调这个函数
	RemoteHit CacheCallback
	// 当调用Get的时候，远程cache miss，会回调这个函数
	RemoteMiss CacheCallback

	// 本地cache实体，在分布式应用中，本地cache一般用于
	// 缓存一些访问热度较高的key(hotkey). 以减轻远程cache
	// 的压力. 但是在更新数据的时候，本地cache的数据不会
	// 被修改. 因此本地cache的TTL应该设置地很短. 并且只有
	// 短期内大量访问的key才应该被缓存到本地.
	LocalCache Cacher
	// 本地cache过期时间
	LocalTTL time.Duration
	// 当调用Get的时候，本地cache命中了，回调该函数
	LocalHit CacheCallback
	// 当调用Get的时候，本地cache miss，回调该函数
	LocalMiss CacheCallback

	// 数据库实体. 用于从数据库获取真实数据. 当缓存全部miss的时候
	// 会从数据库fetch数据并入缓存. 另外可选地，当数据被更新或删除
	// 的时候，除了更新缓存，也会调用数据库的相关接口触发数据库更新
	// 以防止数据不一致的情况
	Database Database

	// 调用更新之后，更新完数据库之后是否异步更新缓存. 如果为true,
	// 则Update函数更新完数据库后会立即返回，异步更新缓存.
	// 因为更新缓存一般不需要同步完成， 建议设置为true.
	UpdateCacheAsync bool

	// 当调用Update之后，缓存的行为. 有以下几种选择：
	//    UpdateActionSet: 调用Update之后更新缓存为最新数据
	//    UpdateActionDel: 调用Update之后删除缓存
	// 在不指定的情况下，默认远程缓存为UpdateActionSet
	// 本地缓存为UpdateActionDel
	RemoteCacheUpdateAction int
	LocalCacheUpdateAction  int

	// 调用Get的时候缓存miss回调函数
	CacheMiss CacheCallback
	// 调用Get的时候命中缓存，并且数据存在的回调函数
	CacheHitFound CacheCallback
	// 调用Get的时候命中缓存，但是数据在数据库不存在的回调函数
	CacheHitNotFound CacheCallback

	// 调用Get的时候更新缓存失败回调函数
	GetSetCacheFail CacheErrCallback
	// 调用Update的时候更新缓存失败回调函数
	UpdateSetCacheFail CacheErrCallback
	// 调用Remove的时候更新缓存失败回调函数
	RemoveSetCacheFail CacheErrCallback

	// 分布式锁，如果运行在分布式环境，请务必设置该对象
	// 这样可以保证获取数据的时候不会获取到脏数据
	// 关于分布式锁的实现，请见cache-lock相关文档
	Lock Locker

	// 是否使用proto对对象进行序列化和反序列化
	// 默认情况下Cache会自动判断是否使用proto
	// 你也可以手动指定
	IsProto bool

	// 是否启动单机hotkey检测
	// 这个检测仅针对本机情况，在分布式环境中，无法
	// 监听到其它实体的hotkey
	HotKeyEnable bool

	// 当认为某个key为hotkey时，是否自动将其加到
	// 本地缓存中去.
	// 如果设为true，为了防止本地缓存导致脏数据
	// 建议将本地缓存过期时间设地短一点
	HotKeySaveToLocal bool

	// 当某个key被标记为hotkey时，会回调这个函数
	HotKeyCallback CacheCallback

	// 标记hotkey的阈值，在HotKeyFlushTime内如果某个key被访问
	// 的次数超过这个值，该key会被标记为hotkey
	HotKeyThreshold int

	// 刷新hotkey的时间间隔. 也是监听hotkey的单位时间
	// 在这个时间内访问次数超过阈值会被标记为hotkey, 当
	// 过了这个时间，hotkey和访问次数都会被全部清空
	HotKeyFlushTime time.Duration

	// 当某个key被标记为hotkey，需要对其做一些操作, 如果
	// 操作失败，回调这个函数
	HotKeyErrCallback CacheErrCallback
	// contains filtered or unexported fields
}

Cache 用于缓存某个对象实体. 提供基于对象的缓存操作. Cache一般用于分布式应用中，即一个对象可能有多个Cache实体运行在不同的机器中. 可以设置两层缓存：本地缓存和远程缓存. 其中远程缓存会被实时更新，本地缓存 一般通过hotkey规则触发或是手动触发. 一般用于分摊远程缓存的压力. 注意Database是必须提供的，它用于从最底层的数据源来获取数据. 注意在使用前调用Init()函数初始化

func (*Cache) AddLocalCache

func (c *Cache) AddLocalCache(key Keyer) error

func (*Cache) Get

func (c *Cache) Get(key Keyer) (interface{}, error)

func (*Cache) Init

func (c *Cache) Init(ptr interface{})

Init 初始化cache，在调用Get, Update, Remove之前，必须调用这个函数 否则会产生未定义的行为! 参数ptr是cache服务的实体的指针, 一般直接将nil强制转换即可, 例如 cache缓存的是User实体，则ptr设为"(*User)(nil)", 依次类推. ptr可以是nil，但是不能是非指针类型，例如int, float等, 否则会直接panic

func (*Cache) IsHotKey

func (c *Cache) IsHotKey(key Keyer) bool

func (*Cache) Remove

func (c *Cache) Remove(key Keyer) error

func (*Cache) Update

func (c *Cache) Update(key Keyer, oper interface{}) (interface{}, error)

type CacheCallback

type CacheCallback func(key Keyer)

type CacheErrCallback

type CacheErrCallback func(key Keyer, err error)

type Cacher

type Cacher interface {
	// 设置缓存, ttl表示缓存的过期时间
	Set(key Keyer, data []byte, ttl time.Duration) error
	// 获取缓存，如果没有找到缓存，请返回ErrCacheMiss错误
	Get(key Keyer) ([]byte, error)
	// 删除缓存
	Del(key Keyer) error
}

Cacher 定义了一个缓存后台的基本操作. 它可以是一个Redis的客户端，也可以 是一个本地LRU缓存. 注意该接口的所有方法都可能会被异步调用，请确保它们是 并发安全的.

func NewLocalCacher

func NewLocalCacher(prefix string, max int) Cacher

func NewRedisClusterCacher

func NewRedisClusterCacher(prefix string, opts *redis.ClusterOptions) Cacher

func NewRedisSingleCacher

func NewRedisSingleCacher(prefix string, opts *redis.Options) Cacher

type Database

type Database interface {
	OnFetch(key Keyer) (interface{}, error)
	OnUpdate(key Keyer, v interface{}) (interface{}, error)
	OnRemove(key Keyer) error
}

type Keyer

type Keyer interface {
	// 以string的形式返回key.
	String() string
	// 以对象的形式返回key.
	Value() interface{}
}

Keyer 用于获取唯一的cache实体. 注意每个cache实体的key应该是唯一的, 具体为，它们返回的String都是不一样的. 如果有多个cache实体使用同一个缓存后台，例如它们共享Redis，则强烈建议 String()的返回值前面加上prefix，不然可能导致不同维度key冲突问题. 例如，User实体和Product实体均使用id作为key，那么如果有一个user的id 等于另一个product的id，它们虽然是不同的实体，但是实际上缓存在了一起. 所以强烈建议加上诸如 "user.", "product." 这样的前缀.

type LocalCacher

type LocalCacher struct {
	Prefix string
	// contains filtered or unexported fields
}

func (*LocalCacher) Del

func (c *LocalCacher) Del(key Keyer) error

func (*LocalCacher) Get

func (c *LocalCacher) Get(key Keyer) ([]byte, error)

func (*LocalCacher) Set

func (c *LocalCacher) Set(key Keyer, data []byte, ttl time.Duration) error

type Locker

type Locker interface {
	Lock() (func(), error)
}

type RedisCacher

type RedisCacher struct {
	Prefix string
	// contains filtered or unexported fields
}

func (*RedisCacher) Del

func (r *RedisCacher) Del(key Keyer) error

func (*RedisCacher) Get

func (r *RedisCacher) Get(key Keyer) ([]byte, error)

func (*RedisCacher) Set

func (r *RedisCacher) Set(key Keyer, data []byte, ttl time.Duration) error

type TypeNotMatchErr

type TypeNotMatchErr struct {
	// contains filtered or unexported fields
}

func (*TypeNotMatchErr) Error

func (t *TypeNotMatchErr) Error() string