hacache

README

缓存组件

读取逻辑

1. 如果缓存内容在有效期内，直接返回
2. 如果缓存内容不在有效期内，但是过期的时间在可接受范围内，返回过期的缓存内容，并触发缓存更新任务，后台更新缓存
3. 如果缓存内容不在有效期内，并且不在可接受过期范围内，强制更新缓存，并返回更新后的内容

更新逻辑

更新缓存时，需要执行原函数，为了避免缓存穿透带来的雪崩，给执行原函数加了并发限制。

1. 如果上述（2） 步中，异步更新缓存触发原函数调用限流，那么直接跳过；
2. 如果上述（3）步中，强制更新缓存触发限流，那么此时强制返回过期缓存，保证服务可用。

Documentation

Index

• Constants
• Variables
• type CachedValue
• type Encoder
• type Event
• type EventCacheExpired
• type EventCacheInvalid
• type HaCache
  • func New(opt *Options) (*HaCache, error)
  • func (hc *HaCache) Do(ctx context.Context, args ...interface{}) (interface{}, error)
  • func (hc *HaCache) FnRun(ctx context.Context, background bool, args ...interface{}) (interface{}, error)
  • func (hc *HaCache) GenCacheKey(args ...interface{}) string
  • func (hc *HaCache) Get(key string) (*CachedValue, error)
  • func (hc *HaCache) Set(key string, data interface{}) error
  • func (hc *HaCache) Trigger(event Event)
• type HaEncoder
  • func NewEncoder(n func() interface{}) *HaEncoder
  • func (enc *HaEncoder) Decode(b []byte) (interface{}, error)
  • func (enc *HaEncoder) Encode(v interface{}) ([]byte, error)
  • func (enc *HaEncoder) NewValue() interface{}
• type MetricType
• type Options
  • func (opt *Options) Init()
• type Stats
  • func (s *Stats) Export() map[MetricType]int32
  • func (s *Stats) Incr(m MetricType, i int32)
  • func (s *Stats) Run()
  • func (s *Stats) Setup(client *statsd.Client)
• type Storage

Constants

const (
	// SkipCache 当缓存 key 为 SkipCache 值时，跳过缓存
	SkipCache = "__hacache_skip_cache__"
	// SkipCacheSet 当值为 true 时，不缓存原函数的返回值
	SkipCacheSet = "__hacache_skip_cache_set__"
)

Variables

var (
	// ErrorFnRunLimited 达到原函数执行并发限制
	ErrorFnRunLimited = errors.New("ha-cache fn run rate limited")
	// ErrorInvalidCacheKey 无效的缓存 key
	ErrorInvalidCacheKey = errors.New("invalid cache key")
)

var CurrentStats = new(Stats)

CurrentStats 全局统计实例

Types

type CachedValue

type CachedValue struct {
	// protobuf message 序列化之后的 bytes
	Bytes []byte
	// 缓存创建的时间戳/s
	CreateTS int64
}

CachedValue 缓存值类型

type Encoder

type Encoder interface {
	Encode(v interface{}) ([]byte, error)
	Decode(b []byte) (interface{}, error)
	NewValue() interface{}
}

Encoder encoder of ha-cache

type Event

type Event interface{}

Event 拉取缓存时，触发的事件类型

type EventCacheExpired

type EventCacheExpired struct {
	Args []interface{}
}

EventCacheExpired 缓存过期，但是可以接受，需要执行原始函数进行更新

type EventCacheInvalid

type EventCacheInvalid struct {
	// Bytes 原始函数返回的结果，需要放到缓存里
	Data interface{}
	// Key 缓存 key
	Key string
}

EventCacheInvalid 缓存无效，需要立即更新

type HaCache

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

HaCache ha-cache struct

func New

func New(opt *Options) (*HaCache, error)

New return a new ha-cache instance nolint: gomnd

func (*HaCache) Do

func (hc *HaCache) Do(ctx context.Context, args ...interface{}) (interface{}, error)

Do 取缓存结果，如果不存在，则更新缓存

func (*HaCache) FnRun

func (hc *HaCache) FnRun(ctx context.Context, background bool, args ...interface{}) (interface{}, error)

FnRun 执行原函数，原函数执行时，受并发限制， 如果是缓存过期异步更新，触发限流直接跳过； 如果是缓存失效同步更新，触发限流服务报错 nolint: gomnd

func (*HaCache) GenCacheKey

func (hc *HaCache) GenCacheKey(args ...interface{}) string

GenCacheKey 生成缓存 key

func (*HaCache) Get

func (hc *HaCache) Get(key string) (*CachedValue, error)

Get get cached value

func (*HaCache) Set

func (hc *HaCache) Set(key string, data interface{}) error

Set set `key` to `msg`

func (*HaCache) Trigger

func (hc *HaCache) Trigger(event Event)

Trigger 触发某个 event (non-blocking)

type HaEncoder

type HaEncoder struct {
	// 函数返回缓存中存的值类型，空值指针
	// 用于将缓存中的值进行反序列化
	NewValueFn func() interface{}
}

HaEncoder default encoder of ha-cache 对于 protobuf message 使用 protobuf 序列化，其他 struct 使用 msgpack

func NewEncoder

func NewEncoder(n func() interface{}) *HaEncoder

NewEncoder return new ha-encoder

func (*HaEncoder) Decode

func (enc *HaEncoder) Decode(b []byte) (interface{}, error)

Decode decode bytes to interface

func (*HaEncoder) Encode

func (enc *HaEncoder) Encode(v interface{}) ([]byte, error)

Encode encode v to bytes

func (*HaEncoder) NewValue

func (enc *HaEncoder) NewValue() interface{}

NewValue return new empty encoder value

type MetricType

type MetricType string

MetricType 指标类型

const (
	// MHit 命中有效缓存
	MHit MetricType = "hit"
	// MMiss 完全 miss
	MMiss MetricType = "miss"
	// MMissExpired 命中过期缓存，但是在可接受过期范围内
	MMissExpired MetricType = "miss-expired"
	// MMissInvalid 命中过期缓存，在最大可接受失效时间范围外
	MMissInvalid MetricType = "miss-invalid"
	// MInvalidReturned 强制返回过期缓存
	MInvalidReturned MetricType = "invalid-returned"
	// MFnRun 执行原函数
	MFnRun MetricType = "fn-run"
	// MFnRunErr 原函数执行出错
	MFnRunErr MetricType = "fn-run-err"
	// MFnRunLimited 原函数执行被限流
	MFnRunLimited MetricType = "fn-run-limited"
	// MEventChanBlocked 事件 channel block 住
	MEventChanBlocked MetricType = "event-chan-blocked"
	// MSkip 不缓存
	MSkip MetricType = "skip"
	// MWorkerPanic worker goroutine panic times
	MWorkerPanic MetricType = "worker-panic"
)

type Options

type Options struct {
	// 缓存穿透、更新时，执行原函数的最大并发数
	// 达到了这个最大并发数，说明原函数处理时间比较长，
	// 有可能是出现某些故障。
	FnRunLimit int32

	// 最大可接受的过期时间
	// 如果缓存过期，并且过期的时间 > MaxAcceptableExpiration，认为该过期的缓存为可接受的数据，
	// 直接返回并触发异步更新缓存任务。如果 过期时间 < MaxAcceptableExpiration ，则认为改数据
	// 不可用，需要立即更新缓存，并将更新后的数据返回。
	MaxAcceptableExpiration time.Duration

	// 缓存过期时间
	Expiration time.Duration

	// 缓存使用的 storage
	Storage Storage

	// 生成缓存 key 的函数，函数参数必须与 Fn 一致
	GenKeyFn interface{}

	// 被缓存的原函数
	Fn interface{}

	// 事件 channel size
	EventBufferSize int32

	// message encoder
	Encoder Encoder

	// logger
	Logger *zap.Logger
}

Options ha-cache options struct

func (*Options) Init

func (opt *Options) Init()

Init setup default value of options

type Stats

type Stats struct {
	// 命中有效缓存次数
	Hit int32
	// 命中失效缓存次数
	MissExpired int32
	// 命中在最大可接受失效时间范围外的次数
	MissInvalid int32
	// 强制返回过期缓存次数
	InvalidReturned int32
	// 完全 miss
	Miss int32
	// 原函数执行次数
	FnRun int32
	// 原函数执行被限流
	FnRunLimited     int32
	FnRunErr         int32
	EventChanBlocked int32
	Skip             int32
	WorkerPanic      int32

	Exporter *statsd.Client
}

Stats 缓存统计数据

func (*Stats) Export

func (s *Stats) Export() map[MetricType]int32

Export 到处统计数据，并清空

func (*Stats) Incr

func (s *Stats) Incr(m MetricType, i int32)

Incr 增加某项指标数据

func (*Stats) Run

func (s *Stats) Run()

Run 上报数据

func (*Stats) Setup

func (s *Stats) Setup(client *statsd.Client)

Setup 设置 statsd 连接

type Storage

type Storage interface {
	Get(key string) ([]byte, error)
	Set(key string, value []byte, expiration time.Duration) error
}

Storage storage is interface of cache