cachex

README

cachex

Go业务层缓存中间件，自带内存LRU存储和Redis存储支持，并支持自定义存储后端

工作机制

cachex由两部分组成：查询引擎和存储后端。

用户逻辑通过查询引擎向存储后端查询缓存，如果查到返回缓存的结果；否则查询引擎调用查询接口获取新的结果，将新结果存储到存储后端，并返回给用户逻辑。

特性

• 支持内存LRU存储、Redis存储，支持自定义存储实现

• 通过哨兵机制解决了单实例内的缓存失效风暴问题

• 支持缓存TTL、查询接口失败返回过期的结果（均需要存储后端支持）

Documentation

Index

• Variables
• type Cachex
  • func NewCachex(storage Storage, querier Querier) (c *Cachex)
  • func (c *Cachex) Del(ctx context.Context, keys ...interface{}) error
  • func (c *Cachex) Get(ctx context.Context, key, value interface{}, opts ...GetOption) error
  • func (c *Cachex) Set(ctx context.Context, key, value interface{}) error
  • func (c *Cachex) SetWithTTL(ctx context.Context, key, value interface{}, TTL time.Duration) error
  • func (c *Cachex) UseStaleWhenError(use bool)
• type ClearableStorage
• type DeletableStorage
• type Expired
• type GetOption
  • func GetQueryOption(querier Querier) GetOption
  • func GetTTLOption(ttl time.Duration) GetOption
• type Keyable
• type NopStorage
  • func (NopStorage) Clear(ctx context.Context) error
  • func (NopStorage) Del(ctx context.Context, keys ...interface{}) error
  • func (NopStorage) Get(ctx context.Context, key, value interface{}) error
  • func (NopStorage) Set(ctx context.Context, key, value interface{}) error
  • func (NopStorage) SetWithTTL(ctx context.Context, key, value interface{}, TTL time.Duration) error
• type NotFound
• type Querier
• type QueryFunc
  • func (fun QueryFunc) Query(ctx context.Context, request, value interface{}) error
• type Sentinel
  • func NewSentinel() *Sentinel
  • func (s *Sentinel) Close()
  • func (s *Sentinel) CloseIfUnclose()
  • func (s *Sentinel) Done(result interface{}, err error) error
  • func (s *Sentinel) Wait(ctx context.Context, result interface{}) error
• type SetWithTTLableStorage
• type Storage

Variables

var (
	// ErrNotFound 没找到
	ErrNotFound = errors.New("not found")

	// ErrNotSupported 操作不支持
	ErrNotSupported = errors.New("not supported operation")
)

var ErrNoResult = errors.New("no result")

ErrNoResult 无结果错误。 消费者等待到的结果无value无err时（生产者panic或编码错误），将会得到该错误。

Types

type Cachex

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

Cachex 缓存处理类

func NewCachex

func NewCachex(storage Storage, querier Querier) (c *Cachex)

NewCachex 新建缓存处理对象

func (*Cachex) Del

func (c *Cachex) Del(ctx context.Context, keys ...interface{}) error

Del 删除

func (*Cachex) Get

func (c *Cachex) Get(ctx context.Context, key, value interface{}, opts ...GetOption) error

Get 获取

func (*Cachex) Set

func (c *Cachex) Set(ctx context.Context, key, value interface{}) error

Set 更新

func (*Cachex) SetWithTTL

func (c *Cachex) SetWithTTL(ctx context.Context, key, value interface{}, TTL time.Duration) error

SetWithTTL 更新，并定制TTL

func (*Cachex) UseStaleWhenError

func (c *Cachex) UseStaleWhenError(use bool)

UseStaleWhenError 设置当查询发生错误时，使用过期的缓存数据。该特性需要Storage支持（Get返回过期的缓存数据和Expired错误实现）。默认关闭。

type ClearableStorage

type ClearableStorage interface {
	Storage
	Clear(ctx context.Context) error
}

ClearableStorage 支持清理操作的存储后端接口

type DeletableStorage

type DeletableStorage interface {
	Storage
	Del(ctx context.Context, keys ...interface{}) error
}

DeletableStorage 支持删除操作的存储后端接口

type Expired

type Expired interface {
	error
	Expired()
}

Expired 已过期错误接口

type GetOption

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

GetOption Get方法的可选参数项结构，不需要直接调用。

func GetQueryOption

func GetQueryOption(querier Querier) GetOption

GetQueryOption 为Get操作定制查询过程。

func GetTTLOption

func GetTTLOption(ttl time.Duration) GetOption

GetTTLOption 为Get操作定制TTL。 需要存储后端支持，否则报错。

type Keyable

type Keyable interface {
	// Key 给Storage的缓存Key
	CacheKey() interface{}
}

Keyable 如果需要包装多个参数为key，包装结构体实现该接口，以支持获取包装结构体的缓存Key。

type NopStorage

type NopStorage struct {
}

NopStorage 一个什么都不干的存储后端。 可以用NopStorage加CacheX组合出一个单实例内不重复查询的机制。

func (NopStorage) Clear

func (NopStorage) Clear(ctx context.Context) error

Clear 实现ClearableStorage接口，只返回nil。

func (NopStorage) Del

func (NopStorage) Del(ctx context.Context, keys ...interface{}) error

Del 实现DeletableStorage接口，只返回nil。

func (NopStorage) Get

func (NopStorage) Get(ctx context.Context, key, value interface{}) error

Get 实现Storage接口，只返回NotFound错误。

func (NopStorage) Set

func (NopStorage) Set(ctx context.Context, key, value interface{}) error

Set 实现Storage接口，只返回nil。

func (NopStorage) SetWithTTL

func (NopStorage) SetWithTTL(ctx context.Context, key, value interface{}, TTL time.Duration) error

SetWithTTL 实现SetWithTTLableStorage接口，只返回nil。

type NotFound

type NotFound interface {
	error
	NotFound()
}

NotFound 没找到错误接口。 需要存储后端找不到缓存时，返回一个实现了NotFound接口的错误。

type Querier

type Querier interface {
	// Query 查询。value必须是非nil指针。没找到返回NotFound错误实现
	Query(ctx context.Context, request, value interface{}) error
}

Querier 查询接口

type QueryFunc

type QueryFunc func(ctx context.Context, request, value interface{}) error

QueryFunc 查询过程签名

func (QueryFunc) Query

func (fun QueryFunc) Query(ctx context.Context, request, value interface{}) error

Query 查询过程实现Querier接口

type Sentinel

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

Sentinel 哨兵。一个生产者，多个消费者等待生产者完成并提交结果

func NewSentinel

func NewSentinel() *Sentinel

NewSentinel 新建哨兵

func (*Sentinel) Close

func (s *Sentinel) Close()

Close 直接关闭。重复关闭内部channel会导致panic。

func (*Sentinel) CloseIfUnclose

func (s *Sentinel) CloseIfUnclose()

CloseIfUnclose 如果未关闭则关闭。

func (*Sentinel) Done

func (s *Sentinel) Done(result interface{}, err error) error

Done 生产者提交结果，消费者将等待到提交的结果。result必须是具体数据变量的接口

func (*Sentinel) Wait

func (s *Sentinel) Wait(ctx context.Context, result interface{}) error

Wait 消费者等待生产者提交结果。result必须是一个指针的接口

type SetWithTTLableStorage

type SetWithTTLableStorage interface {
	Storage
	SetWithTTL(ctx context.Context, key, value interface{}, TTL time.Duration) error
}

SetWithTTLableStorage 支持定制TTL的存储后端接口

type Storage

type Storage interface {
	// Get 获取缓存的数据。value必须是非nil指针。没找到返回NotFound；数据已经过期返回过期数据加NotFound
	Get(ctx context.Context, key, value interface{}) error

	// Set 缓存数据
	Set(ctx context.Context, key, value interface{}) error
}

Storage 存储后端接口