cache

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Jan 20, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package cache 提供了用户数据的缓存功能。 支持内存缓存和 Redis 缓存两种实现,以及基于 Redis 的分布式锁。

Package cache 提供了用户数据的缓存功能。 支持内存缓存和 Redis 缓存两种实现,以及基于 Redis 的分布式锁。

Package cache 提供了用户数据的缓存功能。 支持内存缓存和 Redis 缓存两种实现,以及基于 Redis 的分布式锁。

Package cache 提供了用户数据的缓存功能。 支持内存缓存和 Redis 缓存两种实现,以及基于 Redis 的分布式锁。

Index

Constants

View Source
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
)
View Source
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 NewLocalLocker

func NewLocalLocker() *LocalLocker

NewLocalLocker 创建新的本地锁实例

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

func (s *Locker) Lock(key string) (success bool, err error)

Lock 获取分布式锁,兼容 gocron.Locker 接口

该函数实现了基于 Redis 的分布式锁,使用 SETNX 命令确保原子性。 如果 Redis 不可用,自动降级到本地锁。 锁的默认过期时间为 DefaultLockTime 秒,防止死锁。

参数:

  • key: 锁的键名,用于标识不同的锁

返回:

  • success: true 表示成功获取锁,false 表示锁已被其他进程持有
  • err: 获取锁时发生的错误(如 Redis 连接错误)

副作用:

  • 在 Redis 中设置锁键值对(Redis 模式)
  • 在本地 lockStore 中存储锁值,用于后续解锁验证(Redis 模式)
  • 使用随机生成的锁值,确保只有锁的持有者才能释放锁(Redis 模式)

注意:

  • 锁有自动过期时间,即使进程崩溃也不会导致永久死锁(Redis 模式)
  • 锁值存储在本地内存中,进程重启后会丢失,但锁会在过期时间后自动释放(Redis 模式)
  • 本地锁仅适用于单机部署,多实例时无法防止重复执行

func (*Locker) Unlock

func (s *Locker) Unlock(key string) error

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) Clear

func (c *RedisUserCache) Clear() error

Clear 清除缓存

func (*RedisUserCache) Exists

func (c *RedisUserCache) Exists() (bool, error)

Exists 检查缓存是否存在

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 NewSafeUserCache

func NewSafeUserCache() *SafeUserCache

NewSafeUserCache 创建新的线程安全用户缓存

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) Len

func (c *SafeUserCache) Len() int

Len 获取用户数量(线程安全)

func (*SafeUserCache) Set

func (c *SafeUserCache) Set(users []define.AllowListUser)

Set 设置用户列表(线程安全) 接受切片格式,内部转换为 map 存储 保持输入顺序

Jump to

Keyboard shortcuts

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