Documentation
¶
Overview ¶
Package cache 提供了用户数据的缓存功能。 支持内存缓存和 Redis 缓存两种实现,以及基于 Redis 的分布式锁。
Package cache 提供了用户数据的缓存功能。 支持内存缓存和 Redis 缓存两种实现,以及基于 Redis 的分布式锁。
Package cache 提供了用户数据的缓存功能。 支持内存缓存和 Redis 缓存两种实现,以及基于 Redis 的分布式锁。
Package cache 提供了用户数据的缓存功能。 支持内存缓存和 Redis 缓存两种实现,以及基于 Redis 的分布式锁。
Index ¶
- Constants
- type LocalLocker
- type Locker
- type RedisUserCache
- type SafeUserCache
- func (c *SafeUserCache) Get() []define.AllowListUser
- func (c *SafeUserCache) GetByMail(mail string) (define.AllowListUser, bool)
- func (c *SafeUserCache) GetByPhone(phone string) (define.AllowListUser, bool)
- func (c *SafeUserCache) GetByUserID(userID string) (define.AllowListUser, bool)
- func (c *SafeUserCache) GetHash() string
- func (c *SafeUserCache) GetReadOnly() []define.AllowListUser
- func (c *SafeUserCache) Iterate(fn func(user define.AllowListUser) bool)
- func (c *SafeUserCache) Len() int
- func (c *SafeUserCache) Set(users []define.AllowListUser)
Constants ¶
const ( // REDIS_CACHE_KEY 用于存储用户数据的 Redis key REDIS_CACHE_KEY = "warden:users:cache" // REDIS_CACHE_VERSION_KEY 用于存储缓存版本的 Redis key REDIS_CACHE_VERSION_KEY = "warden:users:cache:version" // REDIS_CACHE_TTL Redis 缓存过期时间(1小时) REDIS_CACHE_TTL = 1 * time.Hour // REDIS_OPERATION_TIMEOUT Redis 操作超时时间 REDIS_OPERATION_TIMEOUT = 5 * time.Second )
const ( // LOCK_OPERATION_TIMEOUT 锁操作超时时间 //nolint:revive // 常量使用 ALL_CAPS 符合项目规范 LOCK_OPERATION_TIMEOUT = 5 * time.Second )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LocalLocker ¶
type LocalLocker struct {
// contains filtered or unexported fields
}
LocalLocker 提供本地锁功能,兼容 gocron.Locker 接口 适用于单机部署场景,不支持分布式环境
func (*LocalLocker) Lock ¶
func (l *LocalLocker) Lock(key string) (success bool, err error)
Lock 获取本地锁,兼容 gocron.Locker 接口
该函数实现了基于 sync.Mutex 的本地锁,适用于单机部署场景。 在分布式环境下,多个实例之间无法协调,可能导致重复执行。
参数:
- key: 锁的键名,用于标识不同的锁
返回:
- success: true 表示成功获取锁,false 表示锁已被持有
- err: 获取锁时发生的错误(本地锁不会返回错误)
注意:
- 本地锁仅适用于单机部署,多实例时无法防止重复执行
- 锁在进程退出时会自动释放
func (*LocalLocker) Unlock ¶
func (l *LocalLocker) Unlock(key string) error
Unlock 释放本地锁,兼容 gocron.Locker 接口
参数:
- key: 锁的键名,必须与 Lock 时使用的键名一致
返回:
- error: 释放锁时发生的错误(本地锁不会返回错误)
type Locker ¶
type Locker struct {
Cache *redis.Client // Redis 客户端,如果为 nil 则使用本地锁
// contains filtered or unexported fields
}
Locker 提供分布式锁功能,兼容 gocron.Locker 接口 支持 Redis 分布式锁和本地锁两种模式
func (*Locker) Lock ¶
Lock 获取分布式锁,兼容 gocron.Locker 接口
该函数实现了基于 Redis 的分布式锁,使用 SETNX 命令确保原子性。 如果 Redis 不可用,自动降级到本地锁。 锁的默认过期时间为 DefaultLockTime 秒,防止死锁。
参数:
- key: 锁的键名,用于标识不同的锁
返回:
- success: true 表示成功获取锁,false 表示锁已被其他进程持有
- err: 获取锁时发生的错误(如 Redis 连接错误)
副作用:
- 在 Redis 中设置锁键值对(Redis 模式)
- 在本地 lockStore 中存储锁值,用于后续解锁验证(Redis 模式)
- 使用随机生成的锁值,确保只有锁的持有者才能释放锁(Redis 模式)
注意:
- 锁有自动过期时间,即使进程崩溃也不会导致永久死锁(Redis 模式)
- 锁值存储在本地内存中,进程重启后会丢失,但锁会在过期时间后自动释放(Redis 模式)
- 本地锁仅适用于单机部署,多实例时无法防止重复执行
func (*Locker) Unlock ¶
Unlock 释放分布式锁,验证锁的所有者
该函数实现了安全的锁释放机制,使用 Lua 脚本确保原子性。 如果 Redis 不可用,自动降级到本地锁。 只有锁值匹配时才会释放锁,防止误释放其他进程的锁。
参数:
- key: 锁的键名,必须与 Lock 时使用的键名一致
返回:
- error: 释放锁时发生的错误,可能的原因包括:
- 锁值不匹配(锁已被其他进程持有或已过期)
- Redis 操作失败
- 锁值类型错误(内部错误)
副作用:
- 从 Redis 中删除锁键(仅当锁值匹配时,Redis 模式)
- 从本地 lockStore 中删除锁值记录(Redis 模式)
安全机制:
- 使用 Lua 脚本确保检查和删除的原子性(Redis 模式)
- 验证锁值,防止误释放其他进程的锁(Redis 模式)
- 如果本地没有存储锁值,会直接删除(向后兼容,但不安全)
注意:
- 必须使用与 Lock 时相同的 key
- 如果锁已过期或被其他进程持有,会返回错误(Redis 模式)
type RedisUserCache ¶
type RedisUserCache struct {
// contains filtered or unexported fields
}
RedisUserCache 提供基于 Redis 的用户缓存
func NewRedisUserCache ¶
func NewRedisUserCache(client *redis.Client) *RedisUserCache
NewRedisUserCache 创建新的 Redis 用户缓存
func (*RedisUserCache) Get ¶
func (c *RedisUserCache) Get() ([]define.AllowListUser, error)
Get 从 Redis 获取用户列表
func (*RedisUserCache) GetVersion ¶
func (c *RedisUserCache) GetVersion() (int64, error)
GetVersion 获取缓存版本号
func (*RedisUserCache) Set ¶
func (c *RedisUserCache) Set(users []define.AllowListUser) error
Set 将用户列表存储到 Redis,并更新版本号
type SafeUserCache ¶
type SafeUserCache struct {
// contains filtered or unexported fields
}
SafeUserCache 提供线程安全的用户缓存 使用 map 结构提高查找效率,同时保持 API 兼容性 维护顺序列表以保持插入顺序 缓存哈希值以优化数据变化检测 维护多个索引以支持通过 phone、mail、user_id 快速查询
func (*SafeUserCache) Get ¶
func (c *SafeUserCache) Get() []define.AllowListUser
Get 获取用户列表的副本(线程安全) 为了保持 API 兼容性,返回切片格式 返回顺序与 Set 时的顺序一致 使用 sync.Pool 优化内存分配
func (*SafeUserCache) GetByMail ¶
func (c *SafeUserCache) GetByMail(mail string) (define.AllowListUser, bool)
GetByMail 根据邮箱获取用户(线程安全,O(1) 查找)
func (*SafeUserCache) GetByPhone ¶
func (c *SafeUserCache) GetByPhone(phone string) (define.AllowListUser, bool)
GetByPhone 根据手机号获取用户(线程安全,O(1) 查找)
func (*SafeUserCache) GetByUserID ¶
func (c *SafeUserCache) GetByUserID(userID string) (define.AllowListUser, bool)
GetByUserID 根据用户ID获取用户(线程安全,O(1) 查找)
func (*SafeUserCache) GetHash ¶
func (c *SafeUserCache) GetHash() string
GetHash 获取缓存的哈希值(线程安全) 如果哈希值未计算,返回空字符串 使用缓存的哈希值可以避免重复计算,提高性能
func (*SafeUserCache) GetReadOnly ¶
func (c *SafeUserCache) GetReadOnly() []define.AllowListUser
GetReadOnly 获取只读视图(实际返回副本,但语义上表示只读) 对于只读场景,建议使用 Iterate 方法以避免复制
func (*SafeUserCache) Iterate ¶
func (c *SafeUserCache) Iterate(fn func(user define.AllowListUser) bool)
Iterate 迭代所有用户,避免复制整个切片(线程安全) 回调函数按插入顺序接收用户数据 如果回调函数返回 false,迭代将停止
func (*SafeUserCache) Set ¶
func (c *SafeUserCache) Set(users []define.AllowListUser)
Set 设置用户列表(线程安全) 接受切片格式,内部转换为 map 存储 保持输入顺序