cache

package
v1.36.0 Latest Latest
Warning

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

Go to latest
Published: Aug 16, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ForgetLoad

func ForgetLoad(key string)

ForgetLoad 清除 singleflight 组内指定 key 的进行中状态(测试与手动失效用)。

func LoadOrStore

func LoadOrStore[T any](key string, loader func() (T, error)) (T, error)

LoadOrStore 防击穿:多个并发请求命中同一个 key 时只执行一次 loader, 其余请求共享结果。loader 返回错误时不会缓存错误结果,后续请求可重试。 典型用法:缓存 miss 后回源数据库时包装 loader。

func SetGlobal added in v1.36.0

func SetGlobal(instance *RedisCache)

SetGlobal 设置全局实例(EnableCache 时自动调用;测试可手动设置)。

Types

type Lock

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

Lock 表示一个已持有的分布式锁。 释放或续期时都会校验持有者 token,防止误删他人持有的锁。

func (*Lock) Renew

func (l *Lock) Renew(ctx context.Context, ttl time.Duration) error

Renew 续期锁;仅持有者 token 匹配时更新过期时间。

func (*Lock) Unlock

func (l *Lock) Unlock(ctx context.Context) error

Unlock 释放锁;只有持有者 token 匹配时才删除(防误删)。 重复释放安全。

type RedisCache

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

RedisCache 封装 go-redis 与本地缓存代理。

func Get added in v1.36.0

func Get() *RedisCache

Get 获取全局 RedisCache 实例;未启用缓存时返回 nil。 业务直接调用,等价于 gbxioc.GetBean[cache.RedisCache]()。

func GetGlobalCache

func GetGlobalCache() *RedisCache

GetGlobalCache 返回最近一次成功初始化的 Redis 缓存实例。 未初始化时返回 nil,调用方必须判空。

func Init

func Init(ctx context.Context, redisOptions RedisOptions) (*RedisCache, error)

Init 初始化 Redis 缓存客户端并执行连通性检查。 初始化失败时关闭已创建的客户端并返回错误;失败后可安全重试(不再被 sync.Once 锁死)。 成功后实例会写入进程级全局变量,供 GetGlobalCache 访问。

func (*RedisCache) Client added in v1.22.0

func (rc *RedisCache) Client() *redis.Client

Client 返回底层原生 Redis 客户端。

func (*RedisCache) Close

func (rc *RedisCache) Close() error

Close 关闭底层 Redis 连接。

func (*RedisCache) Decr added in v1.22.0

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

Decr 自减。

func (*RedisCache) Del added in v1.22.0

func (rc *RedisCache) Del(ctx context.Context, keys ...string) (int64, error)

Del 删除一个或多个 key。

func (*RedisCache) Expire added in v1.22.0

func (rc *RedisCache) Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)

Expire 设置过期时间。

func (*RedisCache) Get

func (rc *RedisCache) Get(key string, value interface{}) (err error)

Get 获取 key 对应的值,反序列化到 value。

func (*RedisCache) GetRedisClient

func (rc *RedisCache) GetRedisClient() *cache.Cache

GetRedisClient 返回底层缓存代理,用于高级操作。

func (*RedisCache) GetString added in v1.22.0

func (rc *RedisCache) GetString(ctx context.Context, key string) (string, error)

GetString 获取字符串值;key 不存在返回 redis.Nil。

func (*RedisCache) HDel added in v1.22.0

func (rc *RedisCache) HDel(ctx context.Context, key string, fields ...string) (int64, error)

HDel 删除哈希字段。

func (*RedisCache) HGet added in v1.22.0

func (rc *RedisCache) HGet(ctx context.Context, key, field string) (string, error)

HGet 获取哈希字段。

func (*RedisCache) HGetAll added in v1.22.0

func (rc *RedisCache) HGetAll(ctx context.Context, key string) (map[string]string, error)

HGetAll 获取整个哈希。

func (*RedisCache) HSet added in v1.22.0

func (rc *RedisCache) HSet(ctx context.Context, key, field string, value interface{}) error

HSet 设置哈希字段。

func (*RedisCache) Health

func (rc *RedisCache) Health(ctx context.Context) error

Health 检查 Redis 连通性。

func (*RedisCache) Incr added in v1.22.0

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

Incr 自增。

func (*RedisCache) IsExists

func (rc *RedisCache) IsExists(key string) bool

IsExists 判断 key 是否存在。

func (*RedisCache) LPush added in v1.22.0

func (rc *RedisCache) LPush(ctx context.Context, key string, values ...interface{}) (int64, error)

LPush 从头部压入。

func (*RedisCache) Lock

func (rc *RedisCache) Lock(ctx context.Context, key string, ttl, waitTimeout time.Duration) (*Lock, error)

Lock 阻塞获取分布式锁,直到成功、超时或 Context 取消。 waitTimeout 非正数时使用 5 秒默认值。

func (*RedisCache) RPop added in v1.22.0

func (rc *RedisCache) RPop(ctx context.Context, key string) (string, error)

RPop 从尾部弹出。

func (*RedisCache) Set

func (rc *RedisCache) Set(Key string, value interface{}) (err error)

Set 使用默认 TTL 添加 key-value。

func (*RedisCache) SetDefaultTTL

func (rc *RedisCache) SetDefaultTTL(ttl time.Duration)

SetDefaultTTL 设置默认过期时间,影响后续未显式指定 TTL 的写入。

func (*RedisCache) SetNX added in v1.22.0

func (rc *RedisCache) SetNX(ctx context.Context, key string, value interface{}, ttl time.Duration) (bool, error)

SetNX 仅当 key 不存在时写入。

func (*RedisCache) SetTtl

func (rc *RedisCache) SetTtl(key string, value interface{}, ttl time.Duration) (err error)

SetTtl 设置 key 及过期时间;ttl 非正数时使用默认 TTL。

func (*RedisCache) SetTtlWithJitter

func (rc *RedisCache) SetTtlWithJitter(ctx context.Context, key string, value interface{}, baseTTL time.Duration) error

SetTtlWithJitter 设置带随机抖动的过期时间,用于避免缓存同时过期导致的雪崩。 实际 TTL 在 baseTTL 的 ±20% 范围内随机;写入失败返回错误。

func (*RedisCache) TryLock

func (rc *RedisCache) TryLock(ctx context.Context, key string, ttl time.Duration) (*Lock, error)

TryLock 尝试获取分布式锁,立即返回。 获取成功返回非 nil Lock;key 已被占用时返回 (nil, nil);错误时返回错误。

type RedisOptions

type RedisOptions redis.Options

RedisOptions 与 go-redis 的 Options 保持等价,供配置结构直接使用。

type RedisTemplate added in v1.22.0

type RedisTemplate interface {
	// Client 返回底层原生 Redis 客户端(高级/原生操作入口)。
	Client() *redis.Client

	// ---- String ----
	// Incr 自增(不存在时从 0 开始);返回自增后的值。
	Incr(ctx context.Context, key string) (int64, error)
	// Decr 自减。
	Decr(ctx context.Context, key string) (int64, error)
	// GetString 获取字符串值。
	GetString(ctx context.Context, key string) (string, error)

	// ---- 通用 ----
	// Del 删除一个或多个 key;返回删除数量。
	Del(ctx context.Context, keys ...string) (int64, error)
	// Expire 设置过期时间;key 不存在返回 false。
	Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)
	// SetNX 仅当 key 不存在时写入(分布式锁/幂等标记);成功返回 true。
	SetNX(ctx context.Context, key string, value interface{}, ttl time.Duration) (bool, error)

	// ---- Hash ----
	// HSet 设置哈希字段。
	HSet(ctx context.Context, key, field string, value interface{}) error
	// HGet 获取哈希字段。
	HGet(ctx context.Context, key, field string) (string, error)
	// HDel 删除哈希字段;返回删除数量。
	HDel(ctx context.Context, key string, fields ...string) (int64, error)
	// HGetAll 获取整个哈希。
	HGetAll(ctx context.Context, key string) (map[string]string, error)

	// ---- List(简单队列) ----
	// LPush 从头部压入;返回列表长度。
	LPush(ctx context.Context, key string, values ...interface{}) (int64, error)
	// RPop 从尾部弹出(配合 LPush 组成 FIFO 队列)。
	RPop(ctx context.Context, key string) (string, error)
}

RedisTemplate 高频操作层(对标 Spring Data Redis 的 RedisTemplate): 在 RedisCache 的缓存封装之外,提供常用数据结构操作(String/Hash/List), 同时暴露原生 *redis.Client 供开发者手动调用原生 API。

用法:

rc := cache.GetGlobalCache()          // 或 builder.EnableCache 后注入
rc.Incr(ctx, "visit:count")
rc.HSet(ctx, "user:1", "name", "connor")
// 需要原生 API 时:
raw := rc.Client()                     // *redis.Client
raw.ZAdd(ctx, "rank", redis.Z{...})

type Rediser

type Rediser interface {
	Get(key string, value interface{}) (err error)                       // 获取key-value
	GetRedisClient() *cache.Cache                                        // 操作redis客户端
	IsExists(key string) bool                                            // 判断key是否存在
	Set(Key string, value interface{}) (err error)                       // 添加key-value
	SetTtl(key string, value interface{}, ttl time.Duration) (err error) // 设置key超时时间
}

Rediser 定义缓存操作接口。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL