cachex

README

cachex

自研高性能内存缓存库:并发分片、精确 LRU 淘汰、独立 TTL 过期、 Singleflight 击穿防护,与 errx / logx 生态打通。

当前状态:v1.5.0。

定位

cachex 不是分布式缓存,不解决「多节点共享」的问题;它解决单进程内 每个业务都要重复的部分:

• 分片锁 + LRU 淘汰,容量超限自动逐出;
• 每条目独立 TTL,惰性过期 + 后台清理;
• GetOrSet 回源加载,并发未命中只回源一次;
• 命中率、逐出量可观测,Metrics 外部注入。
• LRU 刷新可选:WithLRURefresh(1) 精确(默认), WithLRURefresh(n) 采样刷新降低写锁竞争。

所有方法并发安全,可在多个 goroutine 间共享。

快速上手

cache, err := cachex.New(
	cachex.WithCapacity(10000),
	cachex.WithDefaultTTL(5*time.Minute),
)
if err != nil {
	panic(err)
}
defer cache.Close()

cache.SetTTL("user:1", user, 10*time.Minute)
if v, ok := cache.Get("user:1"); ok {
	u := v.(User)
}

// 击穿防护:并发未命中只回源一次
v, err := cachex.GetOrSet(ctx, cache, "user:1", 10*time.Minute,
	func(ctx context.Context) (any, error) {
		return loadUser(ctx, 1)
	})

质量门槛

• 语句覆盖率 100%,race、vet、staticcheck、fuzz、govulncheck 全绿;
• 三平台 CI(ubuntu / windows / macos);
• 性能基准与手写分片 map 同量级(见 docs/performance.md)。

稳定性承诺

• 本库遵循语义化版本;
• 家族约定:破坏性变更统一走 minor 版本(不强制主版本升级);
• 每个版本发布前执行:100% 覆盖率、race、staticcheck、fuzz、 govulncheck 与三平台 CI。

文档

• docs/README.md — 文档索引
• docs/performance.md — 性能基准与方法
• examples/basic — 缓存读写与 TTL
• examples/load — 击穿防护 GetOrSet

License

MIT © lcylpzls

Documentation

Overview

Package cachex 提供分片并发缓存基座（TTL、LRU、事件、指标与链路钩子）。 实现主体位于 internal/core，本包仅暴露稳定公开 API。

Index

• Constants
• func GetOrSet(ctx context.Context, c *Cache, key string, ttl time.Duration, ...) (any, error)
• type Cache
  • func New(opts ...Option) (*Cache, error)
• type CacheEvent
• type EventHook
• type EvictReason
• type Metrics
• type Option
  • func WithCapacity(n int) Option
  • func WithCleanupInterval(d time.Duration) Option
  • func WithDefaultTTL(d time.Duration) Option
  • func WithEventHook(h EventHook) Option
  • func WithLRURefresh(interval int) Option
  • func WithMetrics(m Metrics) Option
  • func WithOnEvicted(fn func(key string, value any, reason EvictReason)) Option
  • func WithShards(n int) Option
  • func WithTraceHook(h TraceHook) Option
• type Stats
• type TraceAttr
• type TraceHook

Constants

const (
	EvictCapacity = core.EvictCapacity
	EvictExpired  = core.EvictExpired
)

const CodeInvalidConfig = core.CodeInvalidConfig

const Version = core.Version

Functions

func GetOrSet

func GetOrSet(ctx context.Context, c *Cache, key string, ttl time.Duration,
	loader func(context.Context) (any, error)) (any, error)

Types

type Cache

type Cache = core.Cache

func New

func New(opts ...Option) (*Cache, error)

type CacheEvent

type CacheEvent = core.CacheEvent

type EventHook

type EventHook = core.EventHook

type EvictReason

type EvictReason = core.EvictReason

type Metrics

type Metrics = metricsx.Sink

type Option

type Option = core.Option

func WithCapacity

func WithCapacity(n int) Option

func WithCleanupInterval

func WithCleanupInterval(d time.Duration) Option

func WithDefaultTTL

func WithDefaultTTL(d time.Duration) Option

func WithEventHook

func WithEventHook(h EventHook) Option

func WithLRURefresh

func WithLRURefresh(interval int) Option

func WithMetrics

func WithMetrics(m Metrics) Option

func WithOnEvicted

func WithOnEvicted(fn func(key string, value any, reason EvictReason)) Option

func WithShards

func WithShards(n int) Option

func WithTraceHook

func WithTraceHook(h TraceHook) Option

type Stats

type Stats = core.Stats

type TraceAttr

type TraceAttr = contract.TraceAttr

type TraceHook

type TraceHook = contract.TraceHook