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

cache

package
v0.8.2 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package cache 是 data 门面子包：缓存域——接口（Cache/CacheAside/BatchGetter/SourceFunc）+ 本地缓存（LocalCache/SingleFlightCache）+ 缓存键构造 + Checker。实现在 pkg/cache。

另含本仓原生扩展 AsideCache（aside.go）：任意 Cache[T] 之上的动态 TTL 回源（SourceFuncWithTTL）与可选 fail-open stale-if-error（WithStaleIfError）。

re-export 自 github.com/oekit/pkg/cache：类型为泛型 type alias（与源包**完全同一类型**， 双向赋值互通）；非泛型函数/变量经 var 引用同一函数值。源包新增导出符号时 本壳需同步（门面跟版税，data 门面化决策已接受）。

Index

Constants

This section is empty.

Variables

View Source 
var HashKey = src.HashKey
View Source 
var Key = src.Key
View Source 
var NewChecker = src.NewChecker
View Source 
var TenantKey = src.TenantKey
View Source 
var UserKey = src.UserKey
View Source 
var WithClock = src.WithClock

Functions

This section is empty.

Types

type AsideCache added in v0.8.2 

type AsideCache[T any] struct {
	// contains filtered or unexported fields
}

AsideCache 是 Cache-Aside 装饰器：在任意 Cache[T] 存储之上提供 回源动态 TTL（SourceFuncWithTTL）与可选 fail-open stale-if-error。

职责分层：

  • inner 只承担值存储（Get/Set/SetWithTTL/Del/Exists）；
  • 回源、null marker、stale 影子由本装饰器负责（backend 无关， 不依赖 inner 是否区分 null marker）。

实现契约（stale-if-error × null marker 组合语义）

与 pkg/cache 包级「实现契约」对齐，并补齐 stale 维度：

  • null marker **不参与** stale 兜底：marker 表示「已知不存在」， 不是陈旧真值。Source 成功返回 (nil, nil) 时清除该键 stale 影子 并写 marker；marker 命中短路返回 (nil, nil)（防穿透，不回源）， 绝不返回旧真值。
  • stale 命中**不刷新 lastAccess**、**不回填**缓存：影子只读兜底， 缓存层仍视为 miss，下次请求继续走回源（陈旧窗口不因读而延长）。
  • Del/DelBatch **清除** stale 影子：写后失效不得被 stale 兜底复活 （否则删掉的数据会以旧值回归）。
  • stale-if-error 默认关闭（fail-closed）：Source 失败直接上抛。
  • 回填 best-effort：SetWithTTL 失败不影响已取到的返回值。
  • 值语义别名警告同 pkg/cache 包级契约——调用方一律只读对待返回的 *T。

实现 CacheAside[T] 与 TTLCacheAside[T]。

func NewAsideCache added in v0.8.2 

func NewAsideCache[T any](inner Cache[T], source SourceFuncWithTTL[T], opts ...AsideOption[T]) *AsideCache[T]

NewAsideCache 构造带回源动态 TTL 的 Cache-Aside 装饰器。

inner 必填（存储后端，如 NewLocalCache 产物，**不要**在其上再配 Source——回源统一由本装饰器持有）；source 必填。 默认 TTL 取 inner 的 Set 语义（ttl<=0 时回填走 Set 而非 SetWithTTL）。 

opts := []cache.AsideOption[Token]{cache.WithStaleIfError[Token](true)}
aside := cache.NewAsideCache(inner, loadTokenWithExpiry, opts...)

func (*AsideCache[T]) Del added in v0.8.2 

func (a *AsideCache[T]) Del(ctx context.Context, key string) error

Del 删除缓存，并清除 stale 影子与 null marker （写后失效不得被 stale 兜底复活）。

func (*AsideCache[T]) DelBatch added in v0.8.2 

func (a *AsideCache[T]) DelBatch(ctx context.Context, keys ...string) error

DelBatch 批量删除缓存。同 Del 清除装饰器侧状态，幂等。

func (*AsideCache[T]) Exists added in v0.8.2 

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

Exists 检查是否存在。对 null marker 返回 true（"缓存知道该 key 不存在" 也是一种存在），与 Cache 契约一致。

func (*AsideCache[T]) Get added in v0.8.2 

func (a *AsideCache[T]) Get(ctx context.Context, key string) (*T, error)

Get 获取缓存。命中 null marker 返回 (nil, nil)（同包级双关契约）。

func (*AsideCache[T]) GetOrLoad added in v0.8.2 

func (a *AsideCache[T]) GetOrLoad(ctx context.Context, key string) (*T, error)

GetOrLoad 获取缓存，未命中经 SourceFuncWithTTL 回源。 回填 TTL 取 source 返回值（<=0 回退默认 TTL）。

func (*AsideCache[T]) GetOrLoadWithTTL added in v0.8.2 

func (a *AsideCache[T]) GetOrLoadWithTTL(ctx context.Context, key string) (*T, error)

GetOrLoadWithTTL 获取缓存，未命中经 SourceFuncWithTTL 回源并按返回 TTL 回填（ttl<=0 回退默认 TTL）。

流程：

  1. null marker 有效 → (nil, nil)，不回源（防穿透）；
  2. inner 命中真值 → 返回并刷新 stale 影子；
  3. 回源：成功 (nil, nil) → 写 null marker 并清除 stale 影子； 成功真值 → 回填（best-effort）并记 stale 影子； 失败 → stale-if-error 开启且有陈旧真值时返回陈旧值（不回填、 不刷新 lastAccess），否则上抛。

func (*AsideCache[T]) Refresh added in v0.8.2 

func (a *AsideCache[T]) Refresh(ctx context.Context, key string) (*T, error)

Refresh 刷新缓存（清除后重新回源，走 GetOrLoadWithTTL 语义）。

func (*AsideCache[T]) Set added in v0.8.2 

func (a *AsideCache[T]) Set(ctx context.Context, key string, value *T) error

Set 设置缓存（inner 默认 TTL），并刷新 stale 影子。

func (*AsideCache[T]) SetWithTTL added in v0.8.2 

func (a *AsideCache[T]) SetWithTTL(ctx context.Context, key string, value *T, ttl time.Duration) error

SetWithTTL 设置缓存（显式 TTL），并刷新 stale 影子。

type AsideOption added in v0.8.2 

type AsideOption[T any] func(*asideConfig[T])

AsideOption 配置 AsideCache（命名对齐仓内硬规则，避免裸 Option）。

func WithAsideNullTTL added in v0.8.2 

func WithAsideNullTTL[T any](d time.Duration) AsideOption[T]

WithAsideNullTTL 设置 null marker 的 TTL。

  • 0（未设置）：默认 1 分钟；
  • 负值：显式禁用空值缓存（每次 GetOrLoad 都重新调 Source）；
  • 正值：按指定时长缓存 null marker。

与 pkg/cache LocalConfig.NullTTL 语义对齐。

func WithOnStale added in v0.8.2 

func WithOnStale[T any](fn OnStaleFunc[T]) AsideOption[T]

WithOnStale 注册 stale 命中上报回调（配合 WithStaleIfError 使用）。 回调在返回陈旧值之前同步调用，不得 panic。

func WithStaleIfError added in v0.8.2 

func WithStaleIfError[T any](enabled bool) AsideOption[T]

WithStaleIfError 开关 fail-open stale-if-error：Source 失败且存在陈旧 真值时返回陈旧值（可经 WithOnStale 上报），仅当无陈旧值才上抛错误。

默认关闭（fail-closed）：Source 失败直接上抛，语义与裸 GetOrLoad 一致。

与 null marker 的组合语义（实现契约）

  • null marker **不参与** stale 兜底：marker 表示「已知不存在」，不是 陈旧真值；Source 成功返回 (nil, nil) 时会清除该键的 stale 影子， 此后 Source 失败只上抛、不复活旧值。
  • stale 命中**不刷新** lastAccess、**不回填**缓存：影子只读兜底， 缓存层仍视为 miss，下次请求继续走回源（陈旧窗口不因读而延长）。
  • Del/DelBatch **清除** stale 影子：写后失效不得被 stale 兜底复活 （否则删掉的数据会以旧值回归）。

type BatchGetter added in v0.8.1 

type BatchGetter[T any] = src.BatchGetter[T]

type Cache 

type Cache[T any] = src.Cache[T]

type CacheAside 

type CacheAside[T any] = src.CacheAside[T]

type Checker added in v0.5.0 

type Checker = src.Checker

type LocalCache 

type LocalCache[T any] = src.LocalCache[T]

func NewLocalCache 

func NewLocalCache[T any](cfg LocalConfig[T]) *LocalCache[T]

NewLocalCache 创建本地缓存（泛型函数无法 var re-export，经包装转发）。

type LocalConfig 

type LocalConfig[T any] = src.LocalConfig[T]

type OnStaleFunc added in v0.8.2 

type OnStaleFunc[T any] func(ctx context.Context, key string, value *T)

OnStaleFunc stale 命中时的上报回调（日志/指标由调用方决定）。

type Option added in v0.5.0 

type Option = src.Option

type SingleFlightCache 

type SingleFlightCache[T any] = src.SingleFlightCache[T]

func NewSingleFlightCache 

func NewSingleFlightCache[T any](inner CacheAside[T]) *SingleFlightCache[T]

NewSingleFlightCache 创建并发回源合并装饰器。

type SourceFunc 

type SourceFunc[T any] = src.SourceFunc[T]

type SourceFuncWithTTL added in v0.8.2 

type SourceFuncWithTTL[T any] func(ctx context.Context, key string) (*T, time.Duration, error)

SourceFuncWithTTL 回源函数：TTL 由回源结果决定，而非构造期常量。

适用于回源响应自带有效期/过期时间的资源（凭证、证书、配额、动态配置等）， 调用方按返回值换算安全 TTL 后由本函数带回；返回 ttl<=0 时回填回退实现 默认 TTL（等价 Set 而非 SetWithTTL）。

值语义与 (nil, nil) 双关、null marker 防穿透同 SourceFunc： 返回 (nil, nil) 表示数据不存在，实现会缓存 null marker。

func SourceFrom added in v0.8.2 

func SourceFrom[T any](fn SourceFunc[T]) SourceFuncWithTTL[T]

SourceFrom 把固定语义的 SourceFunc 适配为 SourceFuncWithTTL （恒返回 ttl=0 → 回填走实现默认 TTL）。

type TTLCacheAside added in v0.8.2 

type TTLCacheAside[T any] interface {
	CacheAside[T]

	// GetOrLoadWithTTL 获取缓存，未命中时经 SourceFuncWithTTL 回源，
	// 回填 TTL 取 source 返回值（<=0 回退默认 TTL）。语义同 GetOrLoad
	// （miss 非 error、null marker 防穿透、回填 best-effort）。
	GetOrLoadWithTTL(ctx context.Context, key string) (*T, error)
}

TTLCacheAside 是 CacheAside 的动态 TTL 扩展：回填 TTL 由 SourceFuncWithTTL 的返回值决定（ttl<=0 回退默认 TTL）。

AsideCache 实现本接口；新增后端若声明本能力，应跑过 github.com/oekit/data/cachetest 的 RunTTL / RunStaleIfError 场景。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.