cache

Documentation

Index

• Variables
• type Cache
  • func NewRedisCache(host string, port int, password string, db int) Cache
• type RedisCache
  • func NewRedisCacheWithClient(client *redis.Client) *RedisCache
  • func (r *RedisCache) Close() error
  • func (r *RedisCache) Decr(ctx context.Context, key string) (int64, error)
  • func (r *RedisCache) Delete(ctx context.Context, key string) error
  • func (r *RedisCache) Exists(ctx context.Context, key string) (bool, error)
  • func (r *RedisCache) Expire(ctx context.Context, key string, expiration time.Duration) error
  • func (r *RedisCache) Flush(ctx context.Context) error
  • func (r *RedisCache) Get(ctx context.Context, key string) ([]byte, error)
  • func (r *RedisCache) GetDel(ctx context.Context, key string) ([]byte, error)
  • func (r *RedisCache) GetObject(ctx context.Context, key string, value any) error
  • func (r *RedisCache) GetObjectDel(ctx context.Context, key string, value any) error
  • func (r *RedisCache) GetOrSet(ctx context.Context, key string, loader func() (any, error), ...) ([]byte, error)
  • func (r *RedisCache) Incr(ctx context.Context, key string) (int64, error)
  • func (r *RedisCache) MGet(ctx context.Context, keys []string) (map[string][]byte, error)
  • func (r *RedisCache) ScanAll(ctx context.Context, pattern string) ([]string, error)
  • func (r *RedisCache) Set(ctx context.Context, key string, value any, expiration time.Duration) error
  • func (r *RedisCache) SetNX(ctx context.Context, key string, value any, expiration time.Duration) (bool, error)
  • func (r *RedisCache) TTL(ctx context.Context, key string) (time.Duration, error)

Variables

var (
	ErrKeyNotFound = errors.New("cache: key not found") // 键不存在
	ErrKeyExpired  = errors.New("cache: key expired")   // 键已过期
)

通用缓存错误

Types

type Cache

type Cache interface {
	// Get 获取缓存
	Get(ctx context.Context, key string) ([]byte, error)
	// GetObject 获取缓存并反序列化为对象,value 必须为指针
	GetObject(ctx context.Context, key string, value any) error
	// MGet 批量获取缓存，返回 key → 原始字节映射
	MGet(ctx context.Context, keys []string) (map[string][]byte, error)
	// Set 设置缓存，expiration=0 表示永不过期
	Set(ctx context.Context, key string, value any, expiration time.Duration) error
	// SetNX 仅当键不存在时设置缓存，返回 true 表示设置成功。
	// 用于分布式锁、防重、限频等需要原子性"检查并设置"的场景。
	SetNX(ctx context.Context, key string, value any, expiration time.Duration) (bool, error)
	// Delete 删除缓存
	Delete(ctx context.Context, key string) error
	// Exists 判断键是否存在
	Exists(ctx context.Context, key string) (bool, error)
	// TTL 获取键剩余过期时间，返回-2表示键不存在，-1表示永不过期
	TTL(ctx context.Context, key string) (time.Duration, error)
	// Expire 设置键的过期时间，不修改值。用于延长已有 key 的 TTL。
	Expire(ctx context.Context, key string, expiration time.Duration) error
	// Incr 原子递增 1，返回递增后的值。键不存在时从 0 开始递增。
	Incr(ctx context.Context, key string) (int64, error)
	// Decr 原子递减 1，返回递减后的值。键不存在时从 0 开始递减。
	Decr(ctx context.Context, key string) (int64, error)
	// GetOrSet 读取缓存，未命中时调用 loader 获取值并写入缓存，返回最终值。
	// 用于缓存穿透保护（cache-aside 模式的一站式封装）。
	GetOrSet(ctx context.Context, key string, loader func() (any, error), expiration time.Duration) ([]byte, error)
	// GetDel 原子读取并删除缓存（Redis GETDEL 命令），返回被删除的原始字节值。
	// key 不存在时返回 ErrKeyNotFound。用于验证码一次性令牌等"读取后即销毁"的场景。
	GetDel(ctx context.Context, key string) ([]byte, error)
	// GetObjectDel 原子读取、反序列化并删除缓存，value 必须为指针。
	// key 不存在时返回 ErrKeyNotFound。
	GetObjectDel(ctx context.Context, key string, value any) error
	// ScanAll 扫描并返回所有匹配指定模式的键（内部使用 SCAN 迭代，避免阻塞 Redis）。
	// 用于批量处理特定前缀的缓存键（如浏览量 flush、清理过期会话等）。
	ScanAll(ctx context.Context, pattern string) ([]string, error)
	// Flush 清空所有缓存
	Flush(ctx context.Context) error
	// Close 关闭缓存客户端（释放资源）
	Close() error
}

Cache 通用缓存接口 所有缓存实现（Redis/内存/Memcached）都必须实现此接口

func NewRedisCache

func NewRedisCache(host string, port int, password string, db int) Cache

NewRedisCache 创建 RedisCache 实例并验证连接

type RedisCache

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

RedisCache 基于 Redis 的缓存实现

func NewRedisCacheWithClient

func NewRedisCacheWithClient(client *redis.Client) *RedisCache

NewRedisCacheWithClient 使用已有的 redis.Client 创建 RedisCache

func (*RedisCache) Close

func (r *RedisCache) Close() error

Close 关闭 Redis 客户端连接

func (*RedisCache) Decr

func (r *RedisCache) Decr(ctx context.Context, key string) (int64, error)

Decr 原子递减 1，返回递减后的值。

func (*RedisCache) Delete

func (r *RedisCache) Delete(ctx context.Context, key string) error

Delete 删除缓存

func (*RedisCache) Exists

func (r *RedisCache) Exists(ctx context.Context, key string) (bool, error)

Exists 判断键是否存在

func (*RedisCache) Expire

func (r *RedisCache) Expire(ctx context.Context, key string, expiration time.Duration) error

Expire 设置键的过期时间，不修改值。

func (*RedisCache) Flush

func (r *RedisCache) Flush(ctx context.Context) error

Flush 清空当前数据库的所有缓存

func (*RedisCache) Get

func (r *RedisCache) Get(ctx context.Context, key string) ([]byte, error)

Get 获取缓存值

func (*RedisCache) GetDel

func (r *RedisCache) GetDel(ctx context.Context, key string) ([]byte, error)

GetDel 调用 go-redis 内置 GETDEL 命令，原子读取并删除缓存（Redis 6.2.0+）

func (*RedisCache) GetObject

func (r *RedisCache) GetObject(ctx context.Context, key string, value any) error

GetObject 获取缓存并反序列化为对象，value 必须为指针

func (*RedisCache) GetObjectDel

func (r *RedisCache) GetObjectDel(ctx context.Context, key string, value any) error

GetObjectDel 原子读取、反序列化并删除缓存，value 必须为指针

func (*RedisCache) GetOrSet

func (r *RedisCache) GetOrSet(ctx context.Context, key string, loader func() (any, error), expiration time.Duration) ([]byte, error)

GetOrSet 读取缓存，未命中时调用 loader 获取值并写入缓存，返回最终值。

func (*RedisCache) Incr

func (r *RedisCache) Incr(ctx context.Context, key string) (int64, error)

Incr 原子递增 1，返回递增后的值。

func (*RedisCache) MGet

func (r *RedisCache) MGet(ctx context.Context, keys []string) (map[string][]byte, error)

MGet 批量获取缓存，返回 key → 原始字节映射。未命中或错误的 key 不出现在结果中。

func (*RedisCache) ScanAll

func (r *RedisCache) ScanAll(ctx context.Context, pattern string) ([]string, error)

ScanAll 使用 Redis SCAN 命令迭代匹配 pattern 的所有键，避免 KEYS 命令阻塞。 返回完整的键列表（空列表表示无匹配）。

func (*RedisCache) Set

func (r *RedisCache) Set(ctx context.Context, key string, value any, expiration time.Duration) error

Set 设置缓存，expiration=0 表示永不过期

func (*RedisCache) SetNX

func (r *RedisCache) SetNX(ctx context.Context, key string, value any, expiration time.Duration) (bool, error)

SetNX 仅当键不存在时设置缓存，返回 true 表示设置成功。

func (*RedisCache) TTL

func (r *RedisCache) TTL(ctx context.Context, key string) (time.Duration, error)

TTL 获取键剩余过期时间 返回 -2 表示键不存在，返回 -1 表示永不过期