Documentation
¶
Overview ¶
Package all 是 data 生态的聚合入口(umbrella module):一次 go get 拉齐 数据访问全家桶,并承载跨子仓组合而成的胶水件(如两级缓存 TwoLevelCache)。
拉取本模块即引入以下能力(依赖矩阵见各子仓 README):
github.com/oekit/data —— 缓存抽象 CacheAside[T] + 本地缓存 + cachetest 契约套件 github.com/oekit/gormx —— SQL/GORM 全家(连接池/审计/OTel 插件、框架无关 CRUD) github.com/oekit/redisx —— Redis 全家(客户端封装、分布式缓存、分布式锁 distlock、限流 ratelimit) github.com/oekit/timertask —— 分片定时任务(FNV-1a 分片、心跳续约)
使用方式:go get github.com/oekit/data/all 后,业务代码仍按能力**直接 import 各子仓的原始包路径**(本包不是 API 门面,不做 re-export):
import (
"github.com/oekit/data/all" // 聚合依赖(blank,保证 require 不被 tidy 清除)
datacache "github.com/oekit/data/cache"
redisxcache "github.com/oekit/redisx/cache"
)
只需要单一能力时,直接 go get 对应子仓即可,不必引入本模块——各子仓 独立版本、独立依赖,按需引入依赖面最小。
本文件以 blank import 固化各子仓依赖:go mod tidy 会清除未被引用的 require,聚合语义全靠这里的 import 维系(新增子仓时同步补一行)。
Index ¶
- type TwoLevelCache
- func (c *TwoLevelCache[T]) Close(ctx context.Context) error
- func (c *TwoLevelCache[T]) Del(ctx context.Context, key string) error
- func (c *TwoLevelCache[T]) DelBatch(ctx context.Context, keys ...string) error
- func (c *TwoLevelCache[T]) Exists(ctx context.Context, key string) (bool, error)
- func (c *TwoLevelCache[T]) Get(ctx context.Context, key string) (*T, error)
- func (c *TwoLevelCache[T]) GetOrLoad(ctx context.Context, key string) (*T, error)
- func (c *TwoLevelCache[T]) Refresh(ctx context.Context, key string) (*T, error)
- func (c *TwoLevelCache[T]) Set(ctx context.Context, key string, value *T) error
- func (c *TwoLevelCache[T]) SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type TwoLevelCache ¶
type TwoLevelCache[T any] struct { // contains filtered or unexported fields }
TwoLevelCache 是两级缓存装饰器:L1 本地缓存(data/cache.LocalCache)+ L2 远端缓存(redisx/cache.RedisCache 等任意 CacheAside 实现)读穿写透组合。
语义分层:
- L1 只缓存真值(命中即返回,不打 L2);**null 防穿透完全委托 L2 的 null marker**(Source 返回 (nil, nil) 时 marker 落在 L2,后续 GetOrLoad 每次 L1 miss 后会查一跳 L2 并被 marker 挡住,不回源);
- GetOrLoad/Get 在 L2 命中后回填 L1(TTL 归 L1 自身的 LocalConfig);
- Set/SetWithTTL 写穿两级;SetWithTTL 的显式 TTL 同时作用于 L1 与 L2 (否则 L1 长驻会吞掉显式短 TTL 的过期语义);
- Del/DelBatch 双删两级(先远端后本地:远端失败时本地已删,读路径 回填的是远端旧值,短窗口不一致;反序则本地旧值会活过整个 L1 TTL);
- Refresh 走 L2 删除重载(marker 一并清除),新值回填 L1。
值语义沿用 data/cache 的实现契约:返回值一律只读对待(L1 返回内部共享 引用,L2 每次反序列化返回新副本);回填 best-effort,失败记日志不阻断。
接口语义(miss 非 error、null marker、Del 幂等)由 github.com/oekit/data/cachetest 契约套件固化(contract_test.go)。
func NewTwoLevelCache ¶
func NewTwoLevelCache[T any](local *datacache.LocalCache[T], remote datacache.CacheAside[T]) *TwoLevelCache[T]
NewTwoLevelCache 创建两级缓存。 local 与 remote 均必填,nil 在构造期 fail-fast(而非首个操作时深层 panic); remote 必须自带 Source(Cache-Aside 回源配置在远端实现上,如 redisxcache.RedisConfig.Source),本类型不重复持有回源函数。
func (*TwoLevelCache[T]) Close ¶
func (c *TwoLevelCache[T]) Close(ctx context.Context) error
Close 停止 L1 本地缓存的后台清理 goroutine(透传 LocalCache 的 Close(ctx) error;Once 幂等,重复调用安全)。
func (*TwoLevelCache[T]) Del ¶
func (c *TwoLevelCache[T]) Del(ctx context.Context, key string) error
Del 双删两级(先远端后本地,理由见类型文档);key 不存在时幂等不报错。
func (*TwoLevelCache[T]) DelBatch ¶
func (c *TwoLevelCache[T]) DelBatch(ctx context.Context, keys ...string) error
DelBatch 双删两级(批量口径同 Del)。空 keys 为幂等 no-op。
func (*TwoLevelCache[T]) Get ¶
func (c *TwoLevelCache[T]) Get(ctx context.Context, key string) (*T, error)
Get 读穿获取:L1 命中直接返回;L2 命中后回填 L1 并返回。
func (*TwoLevelCache[T]) GetOrLoad ¶
func (c *TwoLevelCache[T]) GetOrLoad(ctx context.Context, key string) (*T, error)
GetOrLoad 读穿回源:L1 命中直接返回;L1 miss 时 L2 负责回源与 null marker 防穿透,拿到真值后回填 L1。Source 返回 (nil, nil) 时透传 (nil, nil),L1 不缓存 null(见类型文档的语义分层)。
func (*TwoLevelCache[T]) Refresh ¶
func (c *TwoLevelCache[T]) Refresh(ctx context.Context, key string) (*T, error)
Refresh 刷新:清 L1 后走 L2 的删除重载(null marker 一并清除),新值回填 L1。
func (*TwoLevelCache[T]) Set ¶
func (c *TwoLevelCache[T]) Set(ctx context.Context, key string, value *T) error
Set 写穿两级(各自使用实现的默认 TTL)。
func (*TwoLevelCache[T]) SetWithTTL ¶
func (c *TwoLevelCache[T]) SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error
SetWithTTL 写穿两级,显式 TTL 同时作用于 L1 与 L2。