Documentation
¶
Overview ¶
Package entitycache 提供通用实体缓存抽象。
EntityCache[K, V] 是 K→V 的缓存接口,由两种实现提供服务:
- FullCache:永远写入,等价于现有 SyncMap 行为(用于 admin 维护的小规模实体)
- LRUCache:基于 hashicorp/golang-lru,按容量淘汰,支持 miss 时 RPC 拉取、 负缓存与 apply-if-present 推送语义(用于高基数实体如 token / user)
抽象层不知道任何业务概念。Token 双键索引、关联实体 warm 等组合 行为由 cache.Store 包内的派生层负责。
Index ¶
- Variables
- type Action
- type Config
- type EntityCache
- type FullCache
- func (c *FullCache[K, V]) Apply(action Action, key K, value V)
- func (c *FullCache[K, V]) Delete(key K)
- func (c *FullCache[K, V]) Get(_ context.Context, key K) (V, bool, error)
- func (c *FullCache[K, V]) Len() int
- func (c *FullCache[K, V]) Peek(key K) (V, bool)
- func (c *FullCache[K, V]) Range(fn func(K, V) bool)
- func (c *FullCache[K, V]) Set(key K, value V)
- func (c *FullCache[K, V]) Stats() Stats
- type LRUCache
- func (c *LRUCache[K, V]) Apply(action Action, key K, value V)
- func (c *LRUCache[K, V]) Delete(key K)
- func (c *LRUCache[K, V]) Get(ctx context.Context, key K) (V, bool, error)
- func (c *LRUCache[K, V]) Len() int
- func (c *LRUCache[K, V]) Peek(key K) (V, bool)
- func (c *LRUCache[K, V]) Range(fn func(K, V) bool)
- func (c *LRUCache[K, V]) Set(key K, value V)
- func (c *LRUCache[K, V]) Stats() Stats
- type Loader
- type LoaderFunc
- type Stats
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("entity not found")
ErrNotFound 表示 Loader 已确认 key 在源端不存在。 LRUCache 据此触发负缓存。
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config[K comparable, V any] struct { // Capacity 是最大条目数(必须 > 0)。 Capacity int // Loader 在 Get miss 时被调用。可为 nil(仅本地缓存)。 Loader Loader[K, V] // NegativeTTL 是负缓存("key 不存在")的过期时间。0 表示禁用负缓存。 NegativeTTL time.Duration // Now 用于测试控制时间。零值时使用 time.Now。 Now func() time.Time // OnEvict 在 LRU 因容量淘汰一条**正常**条目时被调用(负缓存条目不触发)。 // 用于派生反向索引同步清理(如 tokenStore.byID)。可为 nil。 OnEvict func(key K, value V) }
Config 是 LRUCache 的构造参数。
type EntityCache ¶
type EntityCache[K comparable, V any] interface { // Get 命中返回 (v, true, nil);未命中且未配置 Loader 返回 (zero, false, nil); // 已配置 Loader 时同步触发拉取。Loader 返回 ErrNotFound 走负缓存 // 后续返回 (zero, false, ErrNotFound);其他错误透传。 Get(ctx context.Context, key K) (V, bool, error) // Peek 仅查本地,不触发 Loader。 Peek(key K) (V, bool) // Apply 处理 push 事件。 // FullCache 永远写入或删除;LRUCache 仅当 key 已在缓存时操作。 Apply(action Action, key K, value V) // Set 直接写入,不经 apply-if-present 检查(用于 FullSync 等主动加载场景)。 Set(key K, value V) // Delete 直接删除。 Delete(key K) // Len 返回当前条目数。 Len() int // Range 遍历当前所有条目。回调返回 false 终止遍历。 Range(func(K, V) bool) // Stats 返回运行计数快照。 Stats() Stats }
EntityCache 是通用实体缓存接口。
type FullCache ¶
type FullCache[K comparable, V any] struct { // contains filtered or unexported fields }
FullCache 永远写入,等价于现有 SyncMap 行为。无 LRU 淘汰、无 Loader。
func NewFullCache ¶
func NewFullCache[K comparable, V any]() *FullCache[K, V]
NewFullCache 创建一个空的 FullCache。
type LRUCache ¶
type LRUCache[K comparable, V any] struct { // contains filtered or unexported fields }
LRUCache 基于 hashicorp/golang-lru,带 Loader、负缓存、metrics。
func NewLRUCache ¶
func NewLRUCache[K comparable, V any](cfg Config[K, V]) (*LRUCache[K, V], error)
NewLRUCache 构造 LRUCache。Capacity <= 0 返回错误(fail-fast)。
func (*LRUCache[K, V]) Get ¶
Get 命中返回 (v, true, nil)。 miss 且配置了 Loader 时通过 singleflight 单飞调用,结果写入缓存。 Loader 返回 ErrNotFound 时进入负缓存(如启用),返回 (zero, false, ErrNotFound)。 Loader 返回其他错误透传不缓存。
type Loader ¶
type Loader[K comparable, V any] interface { Load(ctx context.Context, key K) (V, error) }
Loader 封装一次 miss 时的远端拉取。 返回 ErrNotFound 时缓存写入负条目;其他错误透传不缓存。
type LoaderFunc ¶
type LoaderFunc[K comparable, V any] func(context.Context, K) (V, error)
LoaderFunc 适配普通函数到 Loader 接口。