cache

package module
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2021 License: MIT Imports: 13 Imported by: 0

README

cache

提供一套缓存操作的语义，以及一些已实现的缓存提供器。

功能

  • 缓存key管理
  • 随机过期时间管理
  • 自定义缓存提供器
  • 缓存提供器
    • Redis缓存
    • memory缓存
    • 二级缓存, 不支持Increase。

快速开始

go get -u github.com/thisXYH/cache@latest

注意事项

  • redis cahce provider 的测试用例需要自己提供redis连接信息才能测试成功。
  • concurrent rand source 的测试用例是并发测试，可能需要跑多次才能成功。

使用示例

base use sample

package cache_example

import (
	"fmt"
	"github.com/thisXYH/cache"
	"time"
)

// 创建一个缓存操作对象。
//  指定key的组成: go:cache:test<_flag1><_flag2>
//  指定缓存提供器：内存缓存，设置一分钟清理一次过期 key。
//  指定缓存的过期时间为，10分钟 再加上 2分钟的随机量 上下波动。
//
// 直接声明成全局变量。
var cacheOp *cache.Operation = cache.NewOperation(
	"go", "cache:test", 2,
	cache.NewMemoryCacheProvider(1*time.Minute),
	cache.NewExpirationFromMinute(10, 2))

func doSomething() {
	// 获取 key 操作对象，这个对象中包含了组装好的完整缓存key。
	// cacheOp 指定了两个flag，这边就必须传两个参数，多、少都不行。
	// go:cache:test_unixTime_1 .
	key := cacheOp.Key(time.Now(), true)

	// 获取完整缓存key
	fmt.Println(key.Key)
	// output: go:cache:test_1625123485000_1

	// 设置缓存。
	key.Set("hello world!")

	// 获取缓存。
	var value string
	key.Get(&value)

	// Get 的 panic版本，如果key不存在，直接panic。
	key.MustGet(&value)

	fmt.Println(value)
	// output: hello world!

	// 支持基础类型互转，存进去一个 int8  用 int 去接。
	// 转换的实现逻辑可参考：github.com/cmstar/go-conv 。
	key.Set(int8(8))
	var intV int
	key.Get(&intV)

	fmt.Println(intV)
	// output: 8
}

Documentation

Index

Constants

View Source 
const NoExpiration time.Duration = 0 // 缓存不过期。

Variables

This section is empty.

Functions

This section is empty.

Types

type CacheProvider 

type CacheProvider interface {
	// Get 获取指定缓存值。
	//  @key: cache key.
	//  @value: receive value.
	// return: 如果key存在，value被更新成对应值, 反之value值不做改变。
	Get(key string, value any) error

	// MustGet 是 Get 的 panic 版。
	MustGet(key string, value any)

	// TryGet 尝试获取指定缓存。
	//  @key: cache key.
	//  @value: receive value.
	// return: 若 key 存在，value 被更新成对应值，返回 true；反之 value 值不做改变，返回 false。
	TryGet(key string, value any) (bool, error)

	// Create 仅当缓存键不存在时，创建缓存。
	//  @key: cache key.
	//  @value: receive value.
	//  @t: 过期时长， 0表不过期。
	// return: true表示创建了缓存；false说明缓存已经存在了。
	Create(key string, value any, t time.Duration) (bool, error)

	// MustCreate 是 Create 的 panic 版。
	MustCreate(key string, value any, t time.Duration) bool

	// Set 设置或者更新缓存。
	//  @key: cache key.
	//  @value: receive value.
	//  @t: 过期时长， 0表不过期。
	Set(key string, value any, t time.Duration) error

	// MustSet 是 Set 的 panic 版。
	MustSet(key string, value any, t time.Duration)

	// Remove 移除指定缓存,
	//  @key: cache key.
	// return: true 成功移除；false 缓存不存在。
	Remove(key string) (bool, error)

	// MustRemove 是 Remove 的 panic 版。
	MustRemove(key string) bool

	// Increase 为已存在的指定缓存的值（必须是整数）增加1。
	//  @key: cache key.
	// return: 符合条件返回增加后的值，反之返回默认值，以及对应的 error。
	Increase(key string) (int64, error)

	// MustIncrease 是 Increase 的 panic 版。
	MustIncrease(key string) int64

	// Increase 为指定缓存的值增加一个增量(负数==减法)，如果不存在则创建该缓存。
	//  @key: cache key.
	//  @increment: 增量，如果 key 不存在，则当成新缓存的 value。
	//  @t: 过期时长， 0表不过期。
	// return: 返回增加后的值。
	IncreaseOrCreate(key string, increment int64, t time.Duration) (int64, error)

	// MustIncreaseOrCreate 是 IncreaseOrCreate 的 panic 版。
	MustIncreaseOrCreate(key string, increment int64, t time.Duration) int64
}

CacheProvider 提供一套缓存语义。

type Expiration 

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

Expiration 缓存过期时间。 

var CacheExpirationZero *Expiration = NewExpiration(0, 0) // 缓存不过期。

func NewExpiration 

func NewExpiration(baseExpireTime, randomRangeTime time.Duration) *Expiration

NewExpiration 新建缓存过期时间。 

@baseExpireTime: 基准过期时长，0表不过期。
@randomRangeTime: 随机过期市场，0表不随机，否则baseExpireTime将增加[-randomRangeTime, +randomRangeTime]。

func NewExpirationFromHour 

func NewExpirationFromHour(baseExpireTime, randomRangeTime int64) *Expiration

NewExpirationFromHour 以小时为单位创建缓存过期时间。

func NewExpirationFromMillisecond 

func NewExpirationFromMillisecond(baseExpireTime, randomRangeTime int64) *Expiration

NewExpirationFromMillisecond 以毫秒为单位创建缓存过期时间。

func NewExpirationFromMinute 

func NewExpirationFromMinute(baseExpireTime, randomRangeTime int64) *Expiration

NewExpirationFromMinute 以分钟为单位创建缓存过期时间。

func NewExpirationFromSecond 

func NewExpirationFromSecond(baseExpireTime, randomRangeTime int64) *Expiration

NewExpirationFromSecond 以秒为单位创建缓存过期时间。

func (Expiration) BaseExpireTime 

func (c Expiration) BaseExpireTime() time.Duration

func (*Expiration) NextExpireTime 

func (c *Expiration) NextExpireTime() time.Duration

NextExpireTime 获取一个新的过期时间，如果存在随机量的话，返回值已经过随机量计算。

func (Expiration) RandomRangeTime 

func (c Expiration) RandomRangeTime() time.Duration

type KeyOperation 

type KeyOperation struct {

	// 缓存key。
	Key string
	// contains filtered or unexported fields
}

func (*KeyOperation) Create 

func (keyOp *KeyOperation) Create(value any) (bool, error)

Create 仅当缓存键不存在时，创建缓存。 

return: true表示创建了缓存；false说明缓存已经存在了。

func (*KeyOperation) Get 

func (keyOp *KeyOperation) Get(value any) error

Get 获取指定缓存值。 如果key存在，value被更新成对应值， 反之value值不做改变。

func (*KeyOperation) MustCreate 

func (keyOp *KeyOperation) MustCreate(value any) bool

MustCreate 是 Create 的 panic 版。

func (*KeyOperation) MustGet 

func (keyOp *KeyOperation) MustGet(value any)

MustGet 是 Get 的 panic 版。

func (*KeyOperation) MustRemove 

func (keyOp *KeyOperation) MustRemove() bool

MustRemove 是 Remove 的 panic 版。

func (*KeyOperation) MustSet 

func (keyOp *KeyOperation) MustSet(value any)

MustSet 是 Set 的 panic 版。

func (*KeyOperation) Remove 

func (keyOp *KeyOperation) Remove() (bool, error)

Remove 移除指定缓存, 

return: true成功移除，false缓存不存在。

func (*KeyOperation) Set 

func (keyOp *KeyOperation) Set(value any) error

Set 设置或者更新缓存。

func (*KeyOperation) TryGet 

func (keyOp *KeyOperation) TryGet(value any) (bool, error)

TryGet 尝试获取指定缓存。 若key存在，value被更新成对应值，返回true，反之value值不做改变，返回false。

type Level2CacheProvider 

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

Level2CacheProvider 实现简单的两级缓存，不支持Increase， 两个层次的缓存使用相同的缓存key, 所以两个层级的缓存需要使用不同的缓存提供器，防止相互覆盖。

当一级获取不到，将从二级获取（一般来说，一级回收间隔更短）， 并且根据二级缓存更新一级缓存。

实际上可以看成以 Level 2 为主，Level 1 为辅助，提高访问性能。

func NewLevel2CacheProvider added in v0.1.2 

func NewLevel2CacheProvider(l1, l2 CacheProvider, expireTime *Expiration) *Level2CacheProvider

NewLevel2CacheProvider 新建一个二级缓存提供器。

func (*Level2CacheProvider) Create 

func (p *Level2CacheProvider) Create(key string, value any, t time.Duration) (result bool, err error)

implement CacheProvider.Create .

func (*Level2CacheProvider) Get 

func (p *Level2CacheProvider) Get(key string, value any) error

implement CacheProvider.Get .

func (*Level2CacheProvider) Increase 

func (p *Level2CacheProvider) Increase(key string) (int64, error)

implement CacheProvider.Increase, not implemented, will panic!

func (*Level2CacheProvider) IncreaseOrCreate 

func (p *Level2CacheProvider) IncreaseOrCreate(key string, increment int64, t time.Duration) (int64, error)

implement CacheProvider.IncreaseOrCreate, not implemented, will panic!

func (*Level2CacheProvider) MustCreate 

func (p *Level2CacheProvider) MustCreate(key string, value any, t time.Duration) bool

implement CacheProvider.MustCreate .

func (*Level2CacheProvider) MustGet 

func (p *Level2CacheProvider) MustGet(key string, value any)

implement CacheProvider.MustGet .

func (*Level2CacheProvider) MustIncrease 

func (p *Level2CacheProvider) MustIncrease(key string) int64

implement CacheProvider.MustIncrease, not implemented, will panic!

func (*Level2CacheProvider) MustIncreaseOrCreate 

func (p *Level2CacheProvider) MustIncreaseOrCreate(key string, increment int64, t time.Duration) int64

implement CacheProvider.MustIncreaseOrCreate, not implemented, will panic!

func (*Level2CacheProvider) MustRemove 

func (p *Level2CacheProvider) MustRemove(key string) bool

implement CacheProvider.MustRemove .

func (*Level2CacheProvider) MustSet 

func (p *Level2CacheProvider) MustSet(key string, value any, t time.Duration)

implement CacheProvider.MustSet .

func (*Level2CacheProvider) Remove 

func (p *Level2CacheProvider) Remove(key string) (bool, error)

implement CacheProvider.Remove .

func (*Level2CacheProvider) Set 

func (p *Level2CacheProvider) Set(key string, value any, t time.Duration) error

implement CacheProvider.Set .

func (*Level2CacheProvider) TryGet 

func (p *Level2CacheProvider) TryGet(key string, value any) (result bool, err error)

implement CacheProvider.TryGet .

type MemoryCacheProvider 

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

MemoryCacheProvider 内存类型的缓存提供器。

func NewMemoryCacheProvider 

func NewMemoryCacheProvider(cleanupInterval time.Duration) *MemoryCacheProvider

NewMemoryCacheProvider.

func (*MemoryCacheProvider) Create 

func (cp *MemoryCacheProvider) Create(key string, value any, t time.Duration) (bool, error)

implement CacheProvider.Create .

func (*MemoryCacheProvider) Get 

func (cp *MemoryCacheProvider) Get(key string, value any) error

implement CacheProvider.Get .

func (*MemoryCacheProvider) Increase 

func (cp *MemoryCacheProvider) Increase(key string) (int64, error)

implement CacheProvider.Increase .

func (*MemoryCacheProvider) IncreaseOrCreate 

func (cp *MemoryCacheProvider) IncreaseOrCreate(key string, increment int64, t time.Duration) (int64, error)

implement CacheProvider.IncreaseOrCreate .

func (*MemoryCacheProvider) MustCreate 

func (cp *MemoryCacheProvider) MustCreate(key string, value any, t time.Duration) bool

implement CacheProvider.MustCreate .

func (*MemoryCacheProvider) MustGet 

func (cp *MemoryCacheProvider) MustGet(key string, value any)

implement CacheProvider.MustGet .

func (*MemoryCacheProvider) MustIncrease 

func (cp *MemoryCacheProvider) MustIncrease(key string) int64

implement CacheProvider.MustIncrease .

func (*MemoryCacheProvider) MustIncreaseOrCreate 

func (cp *MemoryCacheProvider) MustIncreaseOrCreate(key string, increment int64, t time.Duration) int64

implement CacheProvider.MustIncreaseOrCreate .

func (*MemoryCacheProvider) MustRemove 

func (cp *MemoryCacheProvider) MustRemove(key string) bool

implement CacheProvider.MustRemove .

func (*MemoryCacheProvider) MustSet 

func (cp *MemoryCacheProvider) MustSet(key string, value any, t time.Duration)

implement CacheProvider.MustSet .

func (*MemoryCacheProvider) Remove 

func (cp *MemoryCacheProvider) Remove(key string) (bool, error)

implement CacheProvider.Remove .

func (*MemoryCacheProvider) Set 

func (cp *MemoryCacheProvider) Set(key string, value any, t time.Duration) error

implement CacheProvider.Set .

func (*MemoryCacheProvider) TryGet 

func (cp *MemoryCacheProvider) TryGet(key string, value any) (bool, error)

implement CacheProvider.TryGet .

type Operation 

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

Operation 缓存操作对象。

func NewOperation 

func NewOperation(cacheNamespace, keyPrefix string, uniqueFlagLen int, cacheProvider CacheProvider, expireTime *Expiration) *Operation

NewOperation 创建一个缓存操作对象。 缓存key分三段 <CacheNamespace>:<Prefix>[:unique flag]。 expireTime: 过期时长， nil 或者 CacheExpirationZero 表不过期。 uniqueFlagLen: 指定用来拼接 [:unique flag] 部分的元素个数。

func (*Operation) Key 

func (c *Operation) Key(keys ...interface{}) *KeyOperation

Key 获取指定key的缓存操作对象。

type RedisCacheProvider 

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

Redis 类型的缓存提供器。

func NewRedisCacheProvider 

func NewRedisCacheProvider(cli redis.Cmdable) *RedisCacheProvider

func (*RedisCacheProvider) Create 

func (cli *RedisCacheProvider) Create(key string, value any, t time.Duration) (bool, error)

implement CacheProvider.Create .

func (*RedisCacheProvider) Get 

func (cli *RedisCacheProvider) Get(key string, value any) error

implement CacheProvider.Get .

func (*RedisCacheProvider) Increase 

func (cli *RedisCacheProvider) Increase(key string) (int64, error)

implement CacheProvider.Increase .

func (*RedisCacheProvider) IncreaseOrCreate 

func (cli *RedisCacheProvider) IncreaseOrCreate(key string, increment int64, t time.Duration) (int64, error)

implement CacheProvider.IncreaseOrCreate .

func (*RedisCacheProvider) MustCreate 

func (cli *RedisCacheProvider) MustCreate(key string, value any, t time.Duration) bool

implement CacheProvider.MustCreate .

func (*RedisCacheProvider) MustGet 

func (cli *RedisCacheProvider) MustGet(key string, value any)

implement CacheProvider.MustGet .

func (*RedisCacheProvider) MustIncrease 

func (cli *RedisCacheProvider) MustIncrease(key string) int64

implement CacheProvider.MustIncrease .

func (*RedisCacheProvider) MustIncreaseOrCreate 

func (cli *RedisCacheProvider) MustIncreaseOrCreate(key string, increment int64, t time.Duration) int64

implement CacheProvider.MustIncreaseOrCreate .

func (*RedisCacheProvider) MustRemove 

func (cli *RedisCacheProvider) MustRemove(key string) bool

implement CacheProvider.MustRemove .

func (*RedisCacheProvider) MustSet 

func (cli *RedisCacheProvider) MustSet(key string, value any, t time.Duration)

implement CacheProvider.MustSet .

func (*RedisCacheProvider) Remove 

func (cli *RedisCacheProvider) Remove(key string) (bool, error)

implement CacheProvider.Remove .

func (*RedisCacheProvider) Set 

func (cli *RedisCacheProvider) Set(key string, value any, t time.Duration) error

implement CacheProvider.Set .

func (*RedisCacheProvider) TryGet 

func (cli *RedisCacheProvider) TryGet(key string, value any) (bool, error)

implement CacheProvider.TryGet .

type UnixTime 

type UnixTime time.Time

UnixTime 毫秒级时间戳。

func (UnixTime) MarshalJSON 

func (t UnixTime) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (UnixTime) String 

func (t UnixTime) String() string

String implements fmt.Stringer.

func (*UnixTime) UnmarshalJSON 

func (t *UnixTime) UnmarshalJSON(bytes []byte) error

UnmarshalJSON implements json.UnmarshalJSON.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.