Help us shape the future of Go! Take the 2026 Go Developer Survey

all

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 7 Imported by: 0

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

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]) Exists

func (c *TwoLevelCache[T]) Exists(ctx context.Context, key string) (bool, error)

Exists 存在性检查:L1 命中为 true,否则查 L2(L2 的 null marker 计存在)。

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。

Jump to

Keyboard shortcuts

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