Documentation
¶
Index ¶
- func ForgetLoad(key string)
- func LoadOrStore[T any](key string, loader func() (T, error)) (T, error)
- func SetGlobal(instance *RedisCache)
- type Lock
- type RedisCache
- func (rc *RedisCache) Client() *redis.Client
- func (rc *RedisCache) Close() error
- func (rc *RedisCache) Decr(ctx context.Context, key string) (int64, error)
- func (rc *RedisCache) Del(ctx context.Context, keys ...string) (int64, error)
- func (rc *RedisCache) Expire(ctx context.Context, key string, ttl time.Duration) (bool, error)
- func (rc *RedisCache) Get(key string, value interface{}) (err error)
- func (rc *RedisCache) GetRedisClient() *cache.Cache
- func (rc *RedisCache) GetString(ctx context.Context, key string) (string, error)
- func (rc *RedisCache) HDel(ctx context.Context, key string, fields ...string) (int64, error)
- func (rc *RedisCache) HGet(ctx context.Context, key, field string) (string, error)
- func (rc *RedisCache) HGetAll(ctx context.Context, key string) (map[string]string, error)
- func (rc *RedisCache) HSet(ctx context.Context, key, field string, value interface{}) error
- func (rc *RedisCache) Health(ctx context.Context) error
- func (rc *RedisCache) Incr(ctx context.Context, key string) (int64, error)
- func (rc *RedisCache) IsExists(key string) bool
- func (rc *RedisCache) LPush(ctx context.Context, key string, values ...interface{}) (int64, error)
- func (rc *RedisCache) Lock(ctx context.Context, key string, ttl, waitTimeout time.Duration) (*Lock, error)
- func (rc *RedisCache) RPop(ctx context.Context, key string) (string, error)
- func (rc *RedisCache) RawClient() *redis.Client
- func (rc *RedisCache) Set(Key string, value interface{}) (err error)
- func (rc *RedisCache) SetDefaultTTL(ttl time.Duration)
- func (rc *RedisCache) SetNX(ctx context.Context, key string, value interface{}, ttl time.Duration) (bool, error)
- func (rc *RedisCache) SetTtl(key string, value interface{}, ttl time.Duration) (err error)
- func (rc *RedisCache) SetTtlWithJitter(ctx context.Context, key string, value interface{}, baseTTL time.Duration) error
- func (rc *RedisCache) TryLock(ctx context.Context, key string, ttl time.Duration) (*Lock, error)
- type RedisOptions
- type RedisTemplate
- type Rediser
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadOrStore ¶
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,防止误删他人持有的锁。
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) 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) 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) Lock ¶
func (rc *RedisCache) Lock(ctx context.Context, key string, ttl, waitTimeout time.Duration) (*Lock, error)
Lock 阻塞获取分布式锁,直到成功、超时或 Context 取消。 waitTimeout 非正数时使用 5 秒默认值。
func (*RedisCache) RawClient ¶ added in v1.56.0
func (rc *RedisCache) RawClient() *redis.Client
RawClient 返回底层 go-redis 客户端(幂等/分布式锁/跨节点广播等高级场景)。 未初始化时返回 nil。
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% 范围内随机;写入失败返回错误。
type RedisOptions ¶
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 定义缓存操作接口。