Documentation
¶
Overview ¶
Package cache 提供泛型缓存门面。
定义 Cache[T] 和 CacheAside[T] 接口，支持多种后端实现：
- LocalCache[T]（本包）: 基于内存的本地缓存（LRU、MaxSize、TTL）
- SingleFlightCache[T]（本包）: 装饰器，防缓存击穿
- RedisCache[T]（子包 data/cache/redis）: 基于 go-redis 的分布式缓存； 拆分子包后本包不传递编译依赖 go-redis，用 LocalCache 的服务无需引入 Redis SDK
Index ¶
- func HashKey(prefix string, args ...any) string
- func Key(parts ...string) string
- func TenantKey(tenantID, suffix string) string
- func UserKey(userID int64, suffix string) string
- type Cache
- type CacheAside
- type LocalCache
- func (c *LocalCache[T]) Clear()
- func (c *LocalCache[T]) Close()
- func (c *LocalCache[T]) Del(ctx context.Context, key string) error
- func (c *LocalCache[T]) DelBatch(ctx context.Context, keys ...string) error
- func (c *LocalCache[T]) Exists(ctx context.Context, key string) (bool, error)
- func (c *LocalCache[T]) Get(ctx context.Context, key string) (*T, error)
- func (c *LocalCache[T]) GetOrLoad(ctx context.Context, key string) (*T, error)
- func (c *LocalCache[T]) Refresh(ctx context.Context, key string) (*T, error)
- func (c *LocalCache[T]) Set(ctx context.Context, key string, value *T) error
- func (c *LocalCache[T]) SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error
- func (c *LocalCache[T]) Size() int
- type LocalConfig
- type SingleFlightCache
- func (sf *SingleFlightCache[T]) Del(ctx context.Context, key string) error
- func (sf *SingleFlightCache[T]) DelBatch(ctx context.Context, keys ...string) error
- func (sf *SingleFlightCache[T]) Exists(ctx context.Context, key string) (bool, error)
- func (sf *SingleFlightCache[T]) Get(ctx context.Context, key string) (*T, error)
- func (sf *SingleFlightCache[T]) GetOrLoad(ctx context.Context, key string) (*T, error)
- func (sf *SingleFlightCache[T]) Refresh(ctx context.Context, key string) (*T, error)
- func (sf *SingleFlightCache[T]) Set(ctx context.Context, key string, value *T) error
- func (sf *SingleFlightCache[T]) SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error
- type SourceFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HashKey ¶
HashKey 基于参数生成 hash key，适用于复杂参数的缓存 key。 哈希取 SHA-256 前 16 位 hex（2026-09-15 治理轮：md5 → sha256，缓存 key 属非加密场景但无需为弱哈希留误用空间；摘要值较 v0.28.x 变化，key 为 进程/缓存生命周期内临时值，无持久化契约）。
cache.HashKey("search", "keyword", 1, 20) // "search:a1b2c3d4e5f6g7h8"
Types ¶
type Cache ¶
type Cache[T any] interface { // Get 获取缓存。 // 返回 (nil, nil) 表示数据不存在。 Get(ctx context.Context, key string) (*T, error) // Set 设置缓存（使用默认 TTL）。 Set(ctx context.Context, key string, value *T) error // SetWithTTL 设置缓存（自定义 TTL）。 SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error // Del 删除缓存。 Del(ctx context.Context, key string) error // DelBatch 批量删除缓存。 DelBatch(ctx context.Context, keys ...string) error // Exists 检查缓存是否存在。 Exists(ctx context.Context, key string) (bool, error) }
Cache 是泛型缓存接口，面向接口编程。 只定义通用的缓存操作，不绑定具体实现或模式。
type CacheAside ¶
type CacheAside[T any] interface { Cache[T] // GetOrLoad 获取缓存，未命中时通过 Source 加载并回填。 // Source 返回 (nil, nil) 时缓存 null marker（默认 1 分钟，防穿透）； // 后续调用命中 null marker 直接返回 (nil, nil)，不再调用 Source。 GetOrLoad(ctx context.Context, key string) (*T, error) // Refresh 刷新缓存（删除后重新从 Source 加载）。 Refresh(ctx context.Context, key string) (*T, error) }
CacheAside 是 Cache-Aside 模式扩展接口。 在 Cache 基础上增加数据源回填、刷新等能力。
type LocalCache ¶
type LocalCache[T any] struct { // contains filtered or unexported fields }
LocalCache 是基于内存的本地缓存实现。 适用于单实例场景或作为二级缓存。 使用 Close() 方法停止后台清理 goroutine；Close 可安全重复调用。
func NewLocalCache ¶
func NewLocalCache[T any](cfg LocalConfig[T]) *LocalCache[T]
NewLocalCache 创建一个本地缓存实例。
func (*LocalCache[T]) Del ¶
func (c *LocalCache[T]) Del(ctx context.Context, key string) error
Del 删除缓存。
func (*LocalCache[T]) DelBatch ¶
func (c *LocalCache[T]) DelBatch(ctx context.Context, keys ...string) error
DelBatch 批量删除缓存。
func (*LocalCache[T]) Get ¶
func (c *LocalCache[T]) Get(ctx context.Context, key string) (*T, error)
Get 获取缓存。 返回 (nil, nil) 表示数据不存在 —— 包括 key 不存在和命中 null marker 两种情况；GetOrLoad 会区分二者实现防穿透。
⚠️ 返回的是缓存内部的 *T（零拷贝，热路径设计）：调用方不得修改指向的 值——会污染缓存并与并发读形成 data race。需要可变副本时自行拷贝。 （RedisCache 每次反序列化返回新副本，两实现语义差异见各自身文档。）
func (*LocalCache[T]) GetOrLoad ¶
func (c *LocalCache[T]) GetOrLoad(ctx context.Context, key string) (*T, error)
GetOrLoad 获取缓存，未命中时通过 Source 加载（Cache-Aside 模式）。 Source 返回 (nil, nil) 时缓存 null marker（默认 1 分钟，可用 NullTTL 调整，负值禁用）；命中 null marker 时直接返回 (nil, nil)，**不会**再调 Source，避免对不存在的 key 形成 thundering-herd 击穿。
func (*LocalCache[T]) Refresh ¶
func (c *LocalCache[T]) Refresh(ctx context.Context, key string) (*T, error)
Refresh 刷新缓存（删除后重新从 Source 加载）。
func (*LocalCache[T]) Set ¶
func (c *LocalCache[T]) Set(ctx context.Context, key string, value *T) error
Set 设置缓存（使用默认 TTL）。
func (*LocalCache[T]) SetWithTTL ¶
func (c *LocalCache[T]) SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error
SetWithTTL 设置缓存（自定义 TTL）。
type LocalConfig ¶
type LocalConfig[T any] struct { // TTL 缓存过期时间。0 表示不过期。 TTL time.Duration // MaxSize 最大缓存条目数。0 表示不限制。 MaxSize int // Source 缓存未命中时的数据获取函数（Cache-Aside 模式）。 Source SourceFunc[T] // NullTTL 空值缓存过期时间（防穿透）。 // - 0（未设置）：使用默认值 1 分钟； // - 负值：显式禁用空值缓存（Source 返回 nil 时不写 null marker， // 下次 GetOrLoad 会重新调用 Source）； // - 正值：按指定时长缓存 null marker。 NullTTL time.Duration }
LocalConfig 配置本地缓存实例。
type SingleFlightCache ¶
type SingleFlightCache[T any] struct { // contains filtered or unexported fields }
SingleFlightCache 是带 singleflight 保护的缓存装饰器。 同一个 key 的并发请求只会有一个实际调用 Source，其他请求等待共享结果。 防止缓存击穿（热点 key 过期时的雷群效应）。
可以包装任何 CacheAside[T] 实现（Redis、本地缓存等）。
func NewSingleFlightCache ¶
func NewSingleFlightCache[T any](inner CacheAside[T]) *SingleFlightCache[T]
NewSingleFlightCache 创建带 singleflight 保护的缓存装饰器。 inner 可以是 RedisCache、LocalCache 或任何实现 CacheAside[T] 的缓存。
func (*SingleFlightCache[T]) Del ¶
func (sf *SingleFlightCache[T]) Del(ctx context.Context, key string) error
Del 删除缓存。
func (*SingleFlightCache[T]) DelBatch ¶
func (sf *SingleFlightCache[T]) DelBatch(ctx context.Context, keys ...string) error
DelBatch 批量删除缓存。
func (*SingleFlightCache[T]) Get ¶
func (sf *SingleFlightCache[T]) Get(ctx context.Context, key string) (*T, error)
Get 获取缓存（纯查询，不触发 Source）。
func (*SingleFlightCache[T]) GetOrLoad ¶
func (sf *SingleFlightCache[T]) GetOrLoad(ctx context.Context, key string) (*T, error)
GetOrLoad 获取缓存，带 singleflight 保护。 同一个 key 的并发请求只会有一个实际调用 Source。
流程：
- 查缓存，命中则直接返回
- 未命中时通过 singleflight 去重，只有一个 goroutine 调用 Source
- Source 返回后回填缓存
- 其他 goroutine 共享同一份结果
func (*SingleFlightCache[T]) Refresh ¶
func (sf *SingleFlightCache[T]) Refresh(ctx context.Context, key string) (*T, error)
Refresh 刷新缓存（带 singleflight 保护）。
func (*SingleFlightCache[T]) Set ¶
func (sf *SingleFlightCache[T]) Set(ctx context.Context, key string, value *T) error
Set 设置缓存。
func (*SingleFlightCache[T]) SetWithTTL ¶
func (sf *SingleFlightCache[T]) SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error
SetWithTTL 设置缓存（自定义 TTL）。
Source Files