@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/cache/l1.go

@@ -0,0 +1,153 @@
+package cache
+
+import (
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+// l1Entry L1 缓存条目
+type l1Entry struct {
+	data      []byte
+	expiresAt time.Time
+}
+
+// L1Cache 本地进程内缓存
+//
+// 使用 sync.Map 实现简单高效的并发安全缓存。
+// 通过后台协程定期清理过期条目，控制内存占用。
+// 未来可替换为 ristretto 以获得 TinyLFU 准入策略和精确内存控制。
+type L1Cache struct {
+	store      sync.Map
+	defaultTTL time.Duration
+	maxItems   int64
+	enabled    bool
+	itemCount  atomic.Int64
+	logger     *zap.Logger
+	stopCh     chan struct{}
+}
+
+// NewL1Cache 创建 L1 缓存
+func NewL1Cache(cfg L1Config, logger *zap.Logger) *L1Cache {
+	c := &L1Cache{
+		defaultTTL: cfg.DefaultTTL,
+		maxItems:   cfg.MaxItems,
+		enabled:    cfg.Enabled,
+		logger:     logger.Named("L1Cache"),
+		stopCh:     make(chan struct{}),
+	}
+
+	if c.enabled {
+		go c.evictLoop()
+	}
+
+	return c
+}
+
+// Get 从 L1 获取值
+func (c *L1Cache) Get(key string) ([]byte, bool) {
+	if !c.enabled {
+		return nil, false
+	}
+
+	val, ok := c.store.Load(key)
+	if !ok {
+		return nil, false
+	}
+
+	entry := val.(*l1Entry) //nolint:errcheck // store 仅存储 *l1Entry，类型断言始终成功
+	if time.Now().After(entry.expiresAt) {
+		c.store.Delete(key)
+		c.itemCount.Add(-1)
+		return nil, false
+	}
+
+	return entry.data, true
+}
+
+// Set 写入 L1
+func (c *L1Cache) Set(key string, value []byte, ttl time.Duration) {
+	if !c.enabled {
+		return
+	}
+
+	if ttl <= 0 {
+		ttl = c.defaultTTL
+	}
+
+	// 检查是否已存在（不增加计数）
+	_, existed := c.store.Load(key)
+
+	c.store.Store(key, &l1Entry{
+		data:      value,
+		expiresAt: time.Now().Add(ttl),
+	})
+
+	if !existed {
+		c.itemCount.Add(1)
+	}
+
+	// 超出最大条目数时触发淘汰
+	if c.itemCount.Load() > c.maxItems {
+		go c.evictExpired()
+	}
+}
+
+// Del 从 L1 删除
+func (c *L1Cache) Del(key string) {
+	if !c.enabled {
+		return
+	}
+	if _, loaded := c.store.LoadAndDelete(key); loaded {
+		c.itemCount.Add(-1)
+	}
+}
+
+// ItemCount 返回当前条目数
+func (c *L1Cache) ItemCount() int64 {
+	return c.itemCount.Load()
+}
+
+// Close 关闭 L1 缓存
+func (c *L1Cache) Close() {
+	if c.enabled {
+		close(c.stopCh)
+	}
+}
+
+// evictLoop 后台定期清理过期条目
+func (c *L1Cache) evictLoop() {
+	ticker := time.NewTicker(30 * time.Second)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-c.stopCh:
+			return
+		case <-ticker.C:
+			c.evictExpired()
+		}
+	}
+}
+
+// evictExpired 清理所有过期条目
+func (c *L1Cache) evictExpired() {
+	now := time.Now()
+	var evicted int64
+
+	c.store.Range(func(key, val any) bool {
+		entry := val.(*l1Entry) //nolint:errcheck // store 仅存储 *l1Entry，类型断言始终成功
+		if now.After(entry.expiresAt) {
+			c.store.Delete(key)
+			evicted++
+		}
+		return true
+	})
+
+	if evicted > 0 {
+		c.itemCount.Add(-evicted)
+		c.logger.Debug("evicted expired L1 entries", zap.Int64("count", evicted))
+	}
+}

package/dist/resources/templates/go-backend/internal/core/cache/l1_test.go

@@ -0,0 +1,212 @@
+package cache
+
+import (
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+)
+
+func newTestL1Cache(enabled bool) *L1Cache {
+	cfg := L1Config{
+		MaxItems:   100,
+		DefaultTTL: 60 * time.Second,
+		Enabled:    enabled,
+	}
+	return NewL1Cache(cfg, zap.NewNop())
+}
+
+func TestL1Cache_SetAndGet(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	key := "test:key"
+	value := []byte(`{"id":1}`)
+
+	c.Set(key, value, time.Minute)
+
+	got, ok := c.Get(key)
+	require.True(t, ok, "期望 Get 返回 true")
+	assert.Equal(t, value, got)
+}
+
+func TestL1Cache_GetExpiredItem(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	key := "expired:key"
+	value := []byte(`"data"`)
+
+	// 写入极短 TTL，使条目立即过期
+	c.Set(key, value, time.Millisecond)
+	time.Sleep(5 * time.Millisecond)
+
+	_, ok := c.Get(key)
+	assert.False(t, ok, "过期条目应返回 false")
+}
+
+func TestL1Cache_GetNonExistent(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	_, ok := c.Get("does:not:exist")
+	assert.False(t, ok, "不存在的键应返回 false")
+}
+
+func TestL1Cache_Delete(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	key := "delete:key"
+	c.Set(key, []byte("value"), time.Minute)
+
+	// 确认写入成功
+	_, ok := c.Get(key)
+	require.True(t, ok)
+
+	c.Del(key)
+
+	_, ok = c.Get(key)
+	assert.False(t, ok, "删除后 Get 应返回 false")
+}
+
+func TestL1Cache_DeleteNonExistent(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	// 删除不存在的键不应 panic，计数不应变为负数
+	c.Del("ghost:key")
+	assert.Equal(t, int64(0), c.ItemCount())
+}
+
+func TestL1Cache_ItemCount(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	assert.Equal(t, int64(0), c.ItemCount())
+
+	c.Set("k1", []byte("v1"), time.Minute)
+	assert.Equal(t, int64(1), c.ItemCount())
+
+	c.Set("k2", []byte("v2"), time.Minute)
+	assert.Equal(t, int64(2), c.ItemCount())
+
+	// 覆盖已有键不应增加计数
+	c.Set("k1", []byte("v1-updated"), time.Minute)
+	assert.Equal(t, int64(2), c.ItemCount())
+
+	c.Del("k1")
+	assert.Equal(t, int64(1), c.ItemCount())
+}
+
+func TestL1Cache_TTLEviction(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	c.Set("expire:soon", []byte("val"), 10*time.Millisecond)
+	c.Set("keep:long", []byte("val"), time.Minute)
+
+	time.Sleep(20 * time.Millisecond)
+
+	_, expiredOk := c.Get("expire:soon")
+	assert.False(t, expiredOk, "短 TTL 条目应已过期")
+
+	_, aliveOk := c.Get("keep:long")
+	assert.True(t, aliveOk, "长 TTL 条目应仍存在")
+}
+
+func TestL1Cache_DefaultTTLUsedWhenZero(t *testing.T) {
+	cfg := L1Config{
+		MaxItems:   100,
+		DefaultTTL: 50 * time.Millisecond,
+		Enabled:    true,
+	}
+	c := NewL1Cache(cfg, zap.NewNop())
+	defer c.Close()
+
+	// TTL=0 时使用 defaultTTL
+	c.Set("default:ttl", []byte("v"), 0)
+	_, ok := c.Get("default:ttl")
+	assert.True(t, ok, "写入后立即 Get 应成功")
+
+	time.Sleep(80 * time.Millisecond)
+
+	_, ok = c.Get("default:ttl")
+	assert.False(t, ok, "defaultTTL 到期后应返回 false")
+}
+
+func TestL1Cache_DisabledCacheAlwaysMisses(t *testing.T) {
+	c := newTestL1Cache(false)
+	// disabled 缓存 stopCh 不关闭，Close() 会 panic，跳过 Close
+
+	c.Set("k", []byte("v"), time.Minute)
+	_, ok := c.Get("k")
+	assert.False(t, ok, "禁用状态下 Get 应始终返回 false")
+	assert.Equal(t, int64(0), c.ItemCount())
+}
+
+func TestL1Cache_ConcurrentReadWrite(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	const goroutines = 50
+	const iterations = 100
+
+	var wg sync.WaitGroup
+	wg.Add(goroutines * 2)
+
+	// 并发写
+	for i := 0; i < goroutines; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			for j := 0; j < iterations; j++ {
+				key := fmt.Sprintf("key:%d:%d", i, j)
+				c.Set(key, []byte("value"), time.Minute)
+			}
+		}()
+	}
+
+	// 并发读
+	for i := 0; i < goroutines; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			for j := 0; j < iterations; j++ {
+				key := fmt.Sprintf("key:%d:%d", i, j)
+				c.Get(key) // 结果可能命中也可能未命中，重点是无竞态
+			}
+		}()
+	}
+
+	wg.Wait()
+	// 若存在竞态，go test -race 会检测到
+}
+
+func TestL1Cache_ConcurrentDelete(t *testing.T) {
+	c := newTestL1Cache(true)
+	defer c.Close()
+
+	// 预填充
+	for i := 0; i < 50; i++ {
+		c.Set(fmt.Sprintf("k%d", i), []byte("v"), time.Minute)
+	}
+
+	var wg sync.WaitGroup
+	wg.Add(50)
+
+	for i := 0; i < 50; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			c.Del(fmt.Sprintf("k%d", i))
+		}()
+	}
+
+	wg.Wait()
+	assert.Equal(t, int64(0), c.ItemCount())
+}

package/dist/resources/templates/go-backend/internal/core/cache/manager.go

@@ -0,0 +1,278 @@
+package cache
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/resilience"
+)
+
+// Manager 统一缓存管理器
+//
+// 提供 L1(进程内) + L2(Redis) 两级缓存的统一操作入口。
+// 所有缓存操作经过 singleflight 去重和熔断器保护。
+//
+// 查找顺序：L1 → singleflight { L2(CircuitBreaker) → loader } → 回填 L1+L2
+type Manager struct {
+	l1         *L1Cache
+	redis      *RedisService
+	sfGroup    singleflightGroup
+	cb         *resilience.CircuitBreakerService
+	metrics    *Metrics
+	serializer Serializer
+	logger     *zap.Logger
+}
+
+// NewManager 创建缓存管理器
+func NewManager(
+	cfg *ManagerConfig,
+	redis *RedisService,
+	l1 *L1Cache,
+	cb *resilience.CircuitBreakerService,
+	metrics *Metrics,
+	logger *zap.Logger,
+) *Manager {
+	return &Manager{
+		l1:         l1,
+		redis:      redis,
+		cb:         cb,
+		metrics:    metrics,
+		serializer: &JSONSerializer{},
+		logger:     logger.Named("Manager"),
+	}
+}
+
+// Get 从缓存获取值，未命中时通过 loader 加载并回填
+//
+// 查找顺序：L1 → L2 → loader
+// singleflight 保证同一 key 同一时刻只有一个 loader 在执行
+func (m *Manager) Get(ctx context.Context, ns *NamespaceConfig, key string, dest any, loader func(ctx context.Context) (any, error), opts ...GetOption) error {
+	o := applyGetOptions(opts)
+	fullKey := ns.Name + ":" + key
+	start := time.Now()
+
+	// 强制刷新时跳过所有缓存层
+	if o.forceRefresh {
+		return m.loadAndFill(ctx, ns, key, fullKey, dest, loader, o)
+	}
+
+	// 步骤 1：检查 L1
+	if ns.L1Enabled && !o.skipL1 {
+		if data, ok := m.l1.Get(fullKey); ok {
+			m.metrics.recordHit(ns.Name, "l1")
+			m.metrics.recordDuration(ns.Name, "get", "l1", time.Since(start).Seconds())
+			return m.serializer.Unmarshal(data, dest)
+		}
+		m.metrics.recordMiss(ns.Name, "l1")
+	}
+
+	// 步骤 2：singleflight 包裹 L2 + loader
+	if ns.Singleflight {
+		result, err, shared := m.sfGroup.do(fullKey, func() (any, error) {
+			return m.getFromL2OrLoad(ctx, ns, key, fullKey, loader, o)
+		})
+		if shared {
+			m.metrics.recordSingleflightDedup(ns.Name)
+		}
+		if err != nil {
+			return err
+		}
+		data := result.([]byte) //nolint:errcheck // getFromL2OrLoad 始终返回 []byte
+		// 回填 L1
+		if ns.L1Enabled && !o.skipL1 {
+			m.l1.Set(fullKey, data, ns.effectiveL1TTL())
+			m.metrics.setL1Items(float64(m.l1.ItemCount()))
+		}
+		return m.serializer.Unmarshal(data, dest)
+	}
+
+	// 不使用 singleflight 时直接走 L2 + loader
+	data, err := m.getFromL2OrLoad(ctx, ns, key, fullKey, loader, o)
+	if err != nil {
+		return err
+	}
+	if ns.L1Enabled && !o.skipL1 {
+		m.l1.Set(fullKey, data, ns.effectiveL1TTL())
+		m.metrics.setL1Items(float64(m.l1.ItemCount()))
+	}
+	return m.serializer.Unmarshal(data, dest)
+}
+
+// Set 显式设置缓存值（L1 + L2）
+func (m *Manager) Set(ctx context.Context, ns *NamespaceConfig, key string, value any, opts ...GetOption) error {
+	o := applyGetOptions(opts)
+	fullKey := ns.Name + ":" + key
+
+	data, err := m.serializer.Marshal(value)
+	if err != nil {
+		return fmt.Errorf("marshal cache value: %w", err)
+	}
+
+	// 计算 L2 TTL
+	l2TTL := ns.L2TTL
+	if o.l2TTLOverride > 0 {
+		l2TTL = o.l2TTLOverride
+	}
+
+	// 写入 L2
+	if err := m.redis.Set(ctx, fullKey, string(data), l2TTL); err != nil {
+		m.logger.Warn("failed to set L2 cache", zap.String("key", fullKey), zap.Error(err))
+		return fmt.Errorf("set L2 cache: %w", err)
+	}
+
+	// 写入 L1
+	if ns.L1Enabled && !o.skipL1 {
+		m.l1.Set(fullKey, data, ns.effectiveL1TTL())
+		m.metrics.setL1Items(float64(m.l1.ItemCount()))
+	}
+
+	return nil
+}
+
+// Invalidate 使缓存条目失效（L1 + L2）
+func (m *Manager) Invalidate(ctx context.Context, ns *NamespaceConfig, key string) error {
+	fullKey := ns.Name + ":" + key
+
+	// 删除 L2
+	if err := m.redis.Del(ctx, fullKey); err != nil {
+		m.logger.Warn("failed to invalidate L2 cache", zap.String("key", fullKey), zap.Error(err))
+	}
+
+	// 删除 L1
+	if ns.L1Enabled {
+		m.l1.Del(fullKey)
+		m.metrics.setL1Items(float64(m.l1.ItemCount()))
+	}
+
+	m.metrics.recordInvalidation(ns.Name)
+	return nil
+}
+
+// InvalidatePrefix 批量失效具有指定前缀的所有缓存条目
+//
+// 注意：L1 无法按前缀删除，仅清理 L2。L1 条目依赖自然过期。
+func (m *Manager) InvalidatePrefix(ctx context.Context, ns *NamespaceConfig, keyPrefix string) error {
+	pattern := ns.Name + ":" + keyPrefix + "*"
+	keys, err := m.redis.ScanKeys(ctx, pattern, 100)
+	if err != nil {
+		return fmt.Errorf("scan keys for invalidation: %w", err)
+	}
+
+	for _, k := range keys {
+		if delErr := m.redis.Del(ctx, k); delErr != nil {
+			m.logger.Warn("failed to invalidate key during prefix cleanup",
+				zap.String("key", k), zap.Error(delErr))
+		}
+	}
+
+	m.metrics.recordInvalidation(ns.Name)
+	return nil
+}
+
+// Exists 检查缓存中是否存在指定 key
+func (m *Manager) Exists(ctx context.Context, ns *NamespaceConfig, key string) (bool, error) {
+	fullKey := ns.Name + ":" + key
+
+	// 检查 L1
+	if ns.L1Enabled {
+		if _, ok := m.l1.Get(fullKey); ok {
+			return true, nil
+		}
+	}
+
+	// 检查 L2
+	return m.redis.Exists(ctx, fullKey)
+}
+
+// Close 关闭缓存管理器，释放资源
+func (m *Manager) Close() {
+	m.l1.Close()
+}
+
+// getFromL2OrLoad 从 L2 获取或通过 loader 加载
+func (m *Manager) getFromL2OrLoad(ctx context.Context, ns *NamespaceConfig, key, fullKey string, loader func(ctx context.Context) (any, error), o *getOptions) ([]byte, error) {
+	start := time.Now()
+
+	// 尝试通过 CircuitBreaker 从 L2 读取
+	cbResult, cbErr := m.cb.Execute(ctx, "cache:redis", func() (any, error) {
+		data, err := m.redis.GetBytes(ctx, fullKey)
+		if err != nil {
+			return nil, err
+		}
+		return data, nil
+	})
+
+	if cbErr != nil {
+		// 熔断器打开或 Redis 错误 — 降级到直接调用 loader
+		var cbOpenErr *resilience.CircuitBreakerOpenError
+		if errors.As(cbErr, &cbOpenErr) {
+			m.metrics.recordCircuitOpen()
+			m.logger.Warn("circuit breaker open, bypassing L2", zap.String("key", fullKey))
+		} else {
+			m.logger.Warn("L2 read failed, falling back to loader", zap.String("key", fullKey), zap.Error(cbErr))
+		}
+		return m.loadFromSource(ctx, ns, key, fullKey, loader, o)
+	}
+
+	// L2 命中
+	if data, ok := cbResult.([]byte); ok && data != nil {
+		m.metrics.recordHit(ns.Name, "l2")
+		m.metrics.recordDuration(ns.Name, "get", "l2", time.Since(start).Seconds())
+		return data, nil
+	}
+
+	// L2 未命中，从 source 加载
+	m.metrics.recordMiss(ns.Name, "l2")
+	return m.loadFromSource(ctx, ns, key, fullKey, loader, o)
+}
+
+// loadFromSource 从数据源加载并回填 L2
+func (m *Manager) loadFromSource(ctx context.Context, ns *NamespaceConfig, _, fullKey string, loader func(ctx context.Context) (any, error), o *getOptions) ([]byte, error) {
+	start := time.Now()
+
+	val, err := loader(ctx)
+	if err != nil {
+		m.metrics.recordSourceLoad(ns.Name, false)
+		return nil, err
+	}
+	m.metrics.recordSourceLoad(ns.Name, true)
+	m.metrics.recordDuration(ns.Name, "get", "source", time.Since(start).Seconds())
+
+	data, err := m.serializer.Marshal(val)
+	if err != nil {
+		return nil, fmt.Errorf("marshal loaded value: %w", err)
+	}
+
+	// 回填 L2（尽力而为）
+	l2TTL := ns.L2TTL
+	if o.l2TTLOverride > 0 {
+		l2TTL = o.l2TTLOverride
+	}
+	if l2TTL > 0 {
+		if setErr := m.redis.Set(ctx, fullKey, string(data), l2TTL); setErr != nil {
+			m.logger.Warn("failed to backfill L2 cache", zap.String("key", fullKey), zap.Error(setErr))
+		}
+	}
+
+	return data, nil
+}
+
+// loadAndFill 强制从 source 加载并回填所有缓存层
+func (m *Manager) loadAndFill(ctx context.Context, ns *NamespaceConfig, key, fullKey string, dest any, loader func(ctx context.Context) (any, error), o *getOptions) error {
+	data, err := m.loadFromSource(ctx, ns, key, fullKey, loader, o)
+	if err != nil {
+		return err
+	}
+
+	// 回填 L1
+	if ns.L1Enabled && !o.skipL1 {
+		m.l1.Set(fullKey, data, ns.effectiveL1TTL())
+		m.metrics.setL1Items(float64(m.l1.ItemCount()))
+	}
+
+	return m.serializer.Unmarshal(data, dest)
+}

package/dist/resources/templates/go-backend/internal/core/cache/manager_provider.go

@@ -0,0 +1,24 @@
+package cache
+
+import "github.com/google/wire"
+
+// ManagerProviderSet Manager 依赖注入 Provider 集合
+//
+// 提供以下依赖：
+//   - L1Config — L1 缓存配置（从 ManagerConfig 提取）
+//   - *L1Cache — 本地进程内缓存
+//   - *Metrics — Prometheus 指标收集
+//   - *Manager — 统一缓存管理器
+//   - *WarmupRegistry — 预热注册表
+var ManagerProviderSet = wire.NewSet(
+	ProvideL1Config,
+	NewL1Cache,
+	NewMetrics,
+	NewManager,
+	NewWarmupRegistry,
+)
+
+// ProvideL1Config 从 ManagerConfig 中提取 L1 缓存配置
+func ProvideL1Config(cfg *ManagerConfig) L1Config {
+	return cfg.L1
+}