rcache

README

rose-cache

一个基于 bigcache 的 Go 缓存库，提供了更丰富的缓存操作接口。

特性

• 支持设置缓存过期时间
• 支持字符串和字节数组存储
• 提供计数器操作（递增/递减）
• 线程安全
• 自动清理过期数据

安装

go get github.com/leafney/rose-cache

快速开始

// 创建一个默认10分钟过期的缓存实例
cache, err := rcache.NewCache(10)
if err != nil {
    log.Fatal(err)
}
defer cache.Close()
// 存储数据
err = cache.XSetEx("key", []byte("value"), 5time.Minute)
// 获取数据
val, err := cache.XGet("key")

配置选项

WithLifeWindow

设置缓存中条目的有效期。超过此时间后，条目将自动从缓存中删除。

WithCleanWindow

设置缓存的清理间隔。每隔此时间段后，缓存会自动检查并删除过期的条目，以保持最佳性能和内存使用。

例如：设置为 10 分钟，则每隔 10 分钟会进行一次过期数据的清理操作。

WithContext

允许为 BigCache 实例设置自定义上下文，用于控制缓存的生命周期。

API 文档

基础操作

// 创建新的缓存实例
func NewCache(minute int64, opts ...Option) (*Cache, error)

// 关闭缓存并释放资源
func (c *Cache) Close() error

// 检查键是否存在
func (c *Cache) Exists(key string) bool

// 删除指定键的缓存项
func (c *Cache) Del(key string) error

基本存取操作

// 设置缓存键值对
func (c *Cache) Set(key string, value []byte) error
func (c *Cache) SetS(key string, value string) error

// 获取缓存值
func (c *Cache) Get(key string) ([]byte, error)
func (c *Cache) GetS(key string) (string, error)

扩展存取操作（支持过期时间）

// 存储数据（支持过期时间）
func (c *Cache) XSet(key string, value []byte) error
func (c *Cache) XSetS(key string, value string) error
func (c *Cache) XSetEx(key string, value []byte, expires time.Duration) error
func (c *Cache) XSetExS(key string, value string, expires time.Duration) error
func (c *Cache) XSetExSec(key string, value []byte, seconds int64) error
func (c *Cache) XSetExSecS(key string, value string, seconds int64) error

// 获取数据
func (c *Cache) XGet(key string) ([]byte, error)
func (c *Cache) XGetS(key string) (string, error)

过期时间操作

// 设置过期时间
func (c *Cache) XExpireAt(key string, tm time.Time) error
func (c *Cache) XExpire(key string, expires time.Duration) error
func (c *Cache) XExpireSec(key string, seconds int64) error

// 获取剩余生存时间（秒）
func (c *Cache) XTTL(key string) (int64, error)

计数器操作

// 递增操作
func (c *Cache) XIncr(key string) (int64, error)
func (c *Cache) XIncrBy(key string, increment int64) (int64, error)

// 递减操作
func (c *Cache) XDecr(key string) (int64, error)
func (c *Cache) XDecrBy(key string, decrement int64) (int64, error)

WithLifeWindow 和 WithCleanWindow 的区别

• WithLifeWindow -- 用来设置缓存的生命周期时长。
• WithCleanWindow -- 用来设置缓存过期后多久被清除的时间，超过该时间，所有过期的条目会被删除，仍在有效期内的条目不会被删除。

错误处理

库定义了以下错误类型：

var (
    ErrKeyEmpty    = errors.New("key is empty")
    ErrKeyNotFound = errors.New("key not found")
    ErrValueEmpty  = errors.New("value is empty")
    ErrNilCache    = errors.New("cache is nil")
)

Documentation

Index

• Variables
• type Cache
  • func NewCache(minute int64, opts ...Option) (*Cache, error)
  • func (c *Cache) Close() error
  • func (c *Cache) Del(key string) error
  • func (c *Cache) Exists(key string) bool
  • func (c *Cache) Get(key string) ([]byte, error)
  • func (c *Cache) GetS(key string) (string, error)
  • func (c *Cache) Set(key string, value []byte) error
  • func (c *Cache) SetS(key string, value string) error
  • func (c *Cache) XDecr(key string) (int64, error)
  • func (c *Cache) XDecrBy(key string, decrement int64) (int64, error)
  • func (c *Cache) XExpire(key string, expires time.Duration) error
  • func (c *Cache) XExpireAt(key string, tm time.Time) error
  • func (c *Cache) XExpireSec(key string, seconds int64) error
  • func (c *Cache) XGet(key string) ([]byte, error)
  • func (c *Cache) XGetS(key string) (string, error)
  • func (c *Cache) XIncr(key string) (int64, error)
  • func (c *Cache) XIncrBy(key string, increment int64) (int64, error)
  • func (c *Cache) XSet(key string, value []byte) error
  • func (c *Cache) XSetEx(key string, value []byte, expires time.Duration) error
  • func (c *Cache) XSetExS(key string, value string, expires time.Duration) error
  • func (c *Cache) XSetExSec(key string, value []byte, seconds int64) error
  • func (c *Cache) XSetExSecS(key string, value string, seconds int64) error
  • func (c *Cache) XSetS(key string, value string) error
  • func (c *Cache) XTTL(key string) (int64, error)
• type CacheType
• type Option
  • func WithCleanWindow(clean time.Duration) Option
  • func WithContext(ctx context.Context) Option
  • func WithLifeWindow(life time.Duration) Option

Variables

var (
	ErrKeyEmpty    = errors.New("key is empty")
	ErrKeyNotFound = errors.New("key not found")
	ErrValueEmpty  = errors.New("value is empty")
	ErrNilCache    = errors.New("cache is nil")
)

Types

type Cache

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

Cache 结构体封装了对 bigcache 的操作

func NewCache

func NewCache(minute int64, opts ...Option) (*Cache, error)

NewCache 返回一个新的 Cache 实例。 minute 参数指定默认的缓存生命周期（分钟） opts 可选参数用于自定义缓存配置

Example:

// 创建一个默认10分钟过期的缓存
cache, err := NewCache(10)

// 创建一个自定义配置的缓存
cache, err := NewCache(10,
    WithLifeWindow(5*time.Minute),
    WithCleanWindow(1*time.Minute),
)

func (*Cache) Close

func (c *Cache) Close() error

Close 关闭缓存并释放资源 在程序结束时调用此方法以确保资源被正确释放

Example:

cache, err := NewCache(10)
if err != nil {
    // 处理错误
}
defer cache.Close()

func (*Cache) Del

func (c *Cache) Del(key string) error

Del 删除指定键的缓存项

func (*Cache) Exists

func (c *Cache) Exists(key string) bool

Exists 检查键是否存在于缓存中

func (*Cache) Get

func (c *Cache) Get(key string) ([]byte, error)

Get 获取指定键的缓存值

func (*Cache) GetS

func (c *Cache) GetS(key string) (string, error)

GetS 获取指定键的字符串类型缓存值

func (*Cache) Set

func (c *Cache) Set(key string, value []byte) error

Set 设置缓存键值对

func (*Cache) SetS

func (c *Cache) SetS(key string, value string) error

SetS 设置字符串类型的缓存键值对

func (*Cache) XDecr

func (c *Cache) XDecr(key string) (int64, error)

XDecr 将键存储的数字值减1

Example:

newVal, err := cache.XDecr("counter")

func (*Cache) XDecrBy

func (c *Cache) XDecrBy(key string, decrement int64) (int64, error)

XDecrBy 将键存储的数字值减少指定的减量

Example:

// 减少5
newVal, err := cache.XDecrBy("counter", 5)

func (*Cache) XExpire

func (c *Cache) XExpire(key string, expires time.Duration) error

XExpire 设置键的过期时间（Duration类型）

Example:

// 设置5分钟后过期
err := cache.XExpire("key", 5*time.Minute)

func (*Cache) XExpireAt

func (c *Cache) XExpireAt(key string, tm time.Time) error

XExpireAt 设置键在指定时间点过期

Example:

// 设置在1小时后过期
err := cache.XExpireAt("key", time.Now().Add(time.Hour))

// 设置在明天零点过期
tomorrow := time.Now().Add(24*time.Hour)
expireTime := time.Date(
    tomorrow.Year(), tomorrow.Month(), tomorrow.Day(),
    0, 0, 0, 0, tomorrow.Location(),
)
err := cache.XExpireAt("key", expireTime)

func (*Cache) XExpireSec

func (c *Cache) XExpireSec(key string, seconds int64) error

XExpireSec 设置键的过期时间（秒数）

func (*Cache) XGet

func (c *Cache) XGet(key string) ([]byte, error)

XGet 获取 gob 序列化存储的数据 如果数据已过期，会自动删除并返回 ErrKeyNotFound

Example:

data, err := cache.XGet("key")
if err == ErrKeyNotFound {
    // 处理键不存在的情况
}

func (*Cache) XGetS

func (c *Cache) XGetS(key string) (string, error)

XGetS 获取 gob 序列化存储的字符串数据

Example:

str, err := cache.XGetS("key")
if err != nil {
    // 处理错误
}

func (*Cache) XIncr

func (c *Cache) XIncr(key string) (int64, error)

XIncr 将键存储的数字值加1 如果键不存在，会创建并设置值为1

Example:

newVal, err := cache.XIncr("counter")
// newVal 是增加后的新值

func (*Cache) XIncrBy

func (c *Cache) XIncrBy(key string, increment int64) (int64, error)

XIncrBy 将键存储的数字值增加指定的增量

Example:

// 增加5
newVal, err := cache.XIncrBy("counter", 5)

// 减少3（通过负数实现）
newVal, err := cache.XIncrBy("counter", -3)

func (*Cache) XSet

func (c *Cache) XSet(key string, value []byte) error

XSet 使用 gob 序列化存储数据，数据永不过期

Example:

err := cache.XSet("key", []byte("value"))

func (*Cache) XSetEx

func (c *Cache) XSetEx(key string, value []byte, expires time.Duration) error

XSetEx 使用 Duration 类型设置过期时间存储数据

Example:

// 存储10分钟后过期的数据
err := cache.XSetEx("key", []byte("value"), 10*time.Minute)

func (*Cache) XSetExS

func (c *Cache) XSetExS(key string, value string, expires time.Duration) error

XSetExS 使用 Duration 类型设置过期时间存储字符串数据

Example:

// 存储1小时后过期的字符串
err := cache.XSetExS("key", "value", time.Hour)

func (*Cache) XSetExSec

func (c *Cache) XSetExSec(key string, value []byte, seconds int64) error

XSetExSec 使用秒数设置过期时间存储数据

func (*Cache) XSetExSecS

func (c *Cache) XSetExSecS(key string, value string, seconds int64) error

XSetExSecS 使用秒数设置过期时间存储字符串数据

func (*Cache) XSetS

func (c *Cache) XSetS(key string, value string) error

XSetS 使用 gob 序列化存储字符串数据，数据永不过期

Example:

err := cache.XSetS("key", "value")

func (*Cache) XTTL

func (c *Cache) XTTL(key string) (int64, error)

XTTL 获取键的剩余生存时间（秒） 返回值说明：

• -2: 键不存在
• -1: 键存在但没有设置过期时间
• >= 0: 剩余生存时间（秒）

Example:

ttl, err := cache.XTTL("key")
switch ttl {
case -2:
    fmt.Println("键不存在")
case -1:
    fmt.Println("键永不过期")
default:
    fmt.Printf("剩余 %d 秒\n", ttl)
}

type CacheType

type CacheType struct {
	Data   []byte
	Expire int64 // 过期时间戳（0表示永不过期）
}

CacheType 定义缓存数据结构

type Option

type Option func(ctx *context.Context, config *bigcache.Config)

func WithCleanWindow

func WithCleanWindow(clean time.Duration) Option

WithCleanWindow 设置缓存的清理频率。 在此时间段内，过期的条目将从缓存中删除。 这有助于保持最佳性能和内存使用，确保过期条目不会滞留在缓存中。

func WithContext

func WithContext(ctx context.Context) Option

WithContext 允许为 BigCache 实例设置自定义上下文。 该上下文可用于控制缓存的生命周期，允许进行取消和超时管理。

func WithLifeWindow

func WithLifeWindow(life time.Duration) Option

WithLifeWindow 设置缓存中条目的有效期。 超过此时间后，条目将自动从缓存中删除。 这有助于管理内存使用，并确保不会提供过时的数据。