cache

cache 包 — 缓存抽象

所属层级: Infrastructure Layer
设计理念: 统一接口，Cache-Aside 模式
设计灵感: Spring Cache + Caffeine

概述

cache 包提供统一的缓存操作接口抽象，支持不同的缓存实现（如 Redis、内存缓存、Caffeine 本地缓存）无缝替换。核心设计模式包括 Cache-Aside（缓存旁路）模式，通过 Getter 函数实现缓存未命中时的数据加载。

核心功能

核心接口

Cache 接口

type Cache interface {
    Get(ctx context.Context, key string) (any, error)
    Set(ctx context.Context, key string, value any, ttl time.Duration) error
    Del(ctx context.Context, keys ...string) error
    Exists(ctx context.Context, key string) (bool, error)
    TTL(ctx context.Context, key string) (time.Duration, error)
    Close() error
}

方法说明

Getter — 数据加载函数

type Getter func(ctx context.Context, key string) (any, error)

用于 Cache-Aside（缓存旁路）模式：当缓存未命中时，通过 Getter 从数据源加载数据并回填缓存。

错误 sentinel

var (
    ErrNotFound  = errors.New("cache: key not found")
    ErrCacheMiss = errors.New("cache: key expired or not found")
)

快速开始

创建内存缓存

package main

import (
    "context"
    "time"
    "github.com/xudefa/enhance/cache"
)

func main() {
    c := cache.NewMemoryCache()
    ctx := context.Background()

    // 设置缓存，5 分钟过期
    err := c.Set(ctx, "user:1", userData, 5*time.Minute)

    // 获取缓存
    val, err := c.Get(ctx, "user:1")
}

Cache-Aside 模式

val, err := c.GetWithGetter(ctx, "user:1", func(ctx context.Context, key string) (any, error) {
    // 从数据库加载
    var user User
    db.First(&user, 1)
    return user, nil
})

API 参考

MemoryCache — 内存缓存实现

基于 sync.RWMutex 和 map[string]cacheItem 的并发安全内存缓存实现，支持 TTL 过期和延迟清理。

创建

cache := cache.NewMemoryCache()

使用场景

• 测试环境
• 轻量级应用
• 缓存原型开发

扩展方法

CaffeineCache — 高性能本地缓存

基于 LRU（最近最少使用）淘汰策略的高性能本地缓存实现，适用于需要控制内存使用量的场景。

创建

// 使用默认配置（最大 1000 项，默认 TTL 5 分钟）
cache := cache.NewCaffeineCache()

// 自定义配置
cache := cache.NewCaffeineCache(
    cache.WithCaffeineMaxSize(5000),
    cache.WithCaffeineDefaultTTL(10*time.Minute),
)

特性

使用示例

c := cache.NewCaffeineCache(cache.WithMaxSize(1000))
ctx := context.Background()

// 设置缓存
_ = c.Set(ctx, "user:1", userData, 5*time.Minute)

// 获取缓存（会更新 LRU 位置）
val, err := c.Get(ctx, "user:1")

// 查看缓存统计
stats := c.Stats()

使用示例

基础操作

c := cache.NewMemoryCache()
ctx := context.Background()

// 设置缓存，5 分钟过期
err := c.Set(ctx, "user:1", userData, 5*time.Minute)

// 获取缓存
val, err := c.Get(ctx, "user:1")
if errors.Is(err, cache.ErrNotFound) {
    // 键不存在
}
if errors.Is(err, cache.ErrCacheMiss) {
    // 键已过期
}

// 检查是否存在
exists, _ := c.Exists(ctx, "user:1")

// 获取剩余 TTL
ttl, _ := c.TTL(ctx, "user:1")

// 批量操作
items := map[string]any{"a": 1, "b": 2}
_ = c.SetMulti(ctx, items, time.Minute)
result, _ := c.GetMulti(ctx, []string{"a", "b"})
_ = c.DeleteMulti(ctx, []string{"a", "b"})

// 清空
_ = c.Clear(ctx)

Cache-Aside 模式

val, err := c.GetWithGetter(ctx, "user:1", func(ctx context.Context, key string) (any, error) {
    // 从数据库加载
    var user User
    db.First(&user, 1)
    return user, nil
})

与依赖注入集成

// 注册为 Bean
container.Register(
    reflect.TypeOf(&cache.MemoryCache{}),
    core.Bean(cache.NewMemoryCache()),
    core.Singleton(),
)

// 注入使用
type UserService struct {
    Cache cache.Cache `inject:"cache"`
}

最佳实践

1. 使用 Cache-Aside 模式简化缓存逻辑

// ✅ 推荐：使用 GetWithGetter 自动回填缓存
val, err := c.GetWithGetter(ctx, "user:1", func(ctx context.Context, key string) (any, error) {
    return db.GetUser(id)
})

// ⚠️ 不推荐：手动实现缓存逻辑
val, err := c.Get(ctx, key)
if err == cache.ErrNotFound {
    val, err = db.GetUser(id)
    if err == nil {
        c.Set(ctx, key, val, ttl)
    }
}

2. 合理设置 TTL

// ✅ 推荐：根据数据更新频率设置合理的 TTL
c.Set(ctx, "user:1", userData, 5*time.Minute)    // 用户数据 5 分钟
c.Set(ctx, "config:app", config, 1*time.Hour)     // 配置数据 1 小时

// ⚠️ 不推荐：所有数据使用相同 TTL
c.Set(ctx, key, value, 10*time.Minute)

3. 使用 CaffeineCache 控制内存使用

// ✅ 推荐：设置最大缓存大小
c := cache.NewCaffeineCache(
    cache.WithCaffeineMaxSize(5000),
    cache.WithCaffeineDefaultTTL(10*time.Minute),
)

// ⚠️ 不推荐：不限制缓存大小，可能导致内存溢出
c := cache.NewMemoryCache()

4. 批量操作提升性能

// ✅ 推荐：使用批量操作
items := map[string]any{"user:1": u1, "user:2": u2}
c.SetMulti(ctx, items, time.Minute)

// ⚠️ 不推荐：循环单个设置
for key, value := range items {
    c.Set(ctx, key, value, time.Minute)
}

5. 与依赖注入集成

// ✅ 推荐：将缓存注册为 Bean
container.Register(
    reflect.TypeOf(&cache.MemoryCache{}),
    core.Bean(cache.NewMemoryCache()),
    core.Singleton(),
)

// 注入使用
type UserService struct {
    Cache cache.Cache `inject:"cache"`
}