@stackonward/cli 0.0.1 → 1.0.1

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

@@ -0,0 +1,126 @@
+package cache
+
+import (
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+// 缓存操作延迟直方图桶定义
+var cacheOperationBuckets = []float64{0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1}
+
+// Metrics 缓存指标收集
+//
+// 独立于 MetricsService 注册 Prometheus collectors，
+// 提供更细粒度的按命名空间和缓存层级的指标。
+type Metrics struct {
+	// 按层和命名空间的命中计数
+	hitsTotal *prometheus.CounterVec
+	// 按层和命名空间的未命中计数
+	missesTotal *prometheus.CounterVec
+	// 从 source 加载的计数
+	sourceLoadsTotal *prometheus.CounterVec
+	// 缓存操作延迟
+	operationDuration *prometheus.HistogramVec
+	// 失效操作计数
+	invalidationsTotal *prometheus.CounterVec
+	// singleflight 去重计数
+	singleflightDedupTotal *prometheus.CounterVec
+	// 熔断器降级计数
+	circuitOpenTotal prometheus.Counter
+	// L1 当前条目数
+	l1ItemsGauge prometheus.Gauge
+}
+
+// NewMetrics 创建缓存指标收集器
+func NewMetrics() *Metrics {
+	return &Metrics{
+		hitsTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "cache_manager_hits_total",
+			Help: "Total number of CacheManager cache hits",
+		}, []string{"namespace", "layer"}),
+
+		missesTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "cache_manager_misses_total",
+			Help: "Total number of CacheManager cache misses",
+		}, []string{"namespace", "layer"}),
+
+		sourceLoadsTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "cache_manager_source_loads_total",
+			Help: "Total number of data source loads",
+		}, []string{"namespace", "success"}),
+
+		operationDuration: promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Name:    "cache_manager_operation_duration_seconds",
+			Help:    "Duration of CacheManager operations in seconds",
+			Buckets: cacheOperationBuckets,
+		}, []string{"namespace", "operation", "layer"}),
+
+		invalidationsTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "cache_manager_invalidations_total",
+			Help: "Total number of cache invalidation operations",
+		}, []string{"namespace"}),
+
+		singleflightDedupTotal: promauto.NewCounterVec(prometheus.CounterOpts{
+			Name: "cache_manager_singleflight_dedup_total",
+			Help: "Total number of deduplicated singleflight requests",
+		}, []string{"namespace"}),
+
+		circuitOpenTotal: promauto.NewCounter(prometheus.CounterOpts{
+			Name: "cache_manager_circuit_open_total",
+			Help: "Total number of Redis circuit breaker open events",
+		}),
+
+		l1ItemsGauge: promauto.NewGauge(prometheus.GaugeOpts{
+			Name: "cache_manager_l1_items",
+			Help: "Current number of items in L1 cache",
+		}),
+	}
+}
+
+// recordHit 记录缓存命中
+func (m *Metrics) recordHit(namespace, layer string) {
+	m.hitsTotal.With(prometheus.Labels{"namespace": namespace, "layer": layer}).Inc()
+}
+
+// recordMiss 记录缓存未命中
+func (m *Metrics) recordMiss(namespace, layer string) {
+	m.missesTotal.With(prometheus.Labels{"namespace": namespace, "layer": layer}).Inc()
+}
+
+// recordSourceLoad 记录数据源加载
+func (m *Metrics) recordSourceLoad(namespace string, success bool) {
+	s := "true"
+	if !success {
+		s = "false"
+	}
+	m.sourceLoadsTotal.With(prometheus.Labels{"namespace": namespace, "success": s}).Inc()
+}
+
+// recordDuration 记录操作延迟
+func (m *Metrics) recordDuration(namespace, operation, layer string, seconds float64) {
+	m.operationDuration.With(prometheus.Labels{
+		"namespace": namespace,
+		"operation": operation,
+		"layer":     layer,
+	}).Observe(seconds)
+}
+
+// recordInvalidation 记录缓存失效
+func (m *Metrics) recordInvalidation(namespace string) {
+	m.invalidationsTotal.With(prometheus.Labels{"namespace": namespace}).Inc()
+}
+
+// recordSingleflightDedup 记录 singleflight 去重
+func (m *Metrics) recordSingleflightDedup(namespace string) {
+	m.singleflightDedupTotal.With(prometheus.Labels{"namespace": namespace}).Inc()
+}
+
+// recordCircuitOpen 记录熔断器打开
+func (m *Metrics) recordCircuitOpen() {
+	m.circuitOpenTotal.Inc()
+}
+
+// setL1Items 设置 L1 条目数
+func (m *Metrics) setL1Items(count float64) {
+	m.l1ItemsGauge.Set(count)
+}

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

@@ -0,0 +1,46 @@
+package cache
+
+import "time"
+
+// SerializationFormat 序列化格式
+type SerializationFormat string
+
+const (
+	// SerializationJSON JSON 序列化
+	SerializationJSON SerializationFormat = "json"
+)
+
+// NamespaceConfig 命名空间配置
+//
+// 每个缓存命名空间定义独立的 TTL、L1 策略和序列化方式。
+// 模块在自身 cache 文件中以包级变量定义。
+type NamespaceConfig struct {
+	// 命名空间名称（如 "identity_session", "apikey_key"）
+	Name string
+	// L2 (Redis) TTL
+	L2TTL time.Duration
+	// L1 (本地缓存) TTL，为 0 时自动取 min(L2TTL/4, 120s)
+	L1TTL time.Duration
+	// 是否启用 L1 缓存（默认 false，需显式开启）
+	L1Enabled bool
+	// 序列化格式（默认 JSON）
+	Serialization SerializationFormat
+	// 是否启用 singleflight（默认 true）
+	Singleflight bool
+}
+
+// effectiveL1TTL 计算实际 L1 TTL
+func (ns *NamespaceConfig) effectiveL1TTL() time.Duration {
+	if ns.L1TTL > 0 {
+		return ns.L1TTL
+	}
+	// 自动计算：min(L2TTL/4, 120s)
+	auto := ns.L2TTL / 4
+	if auto > 120*time.Second {
+		return 120 * time.Second
+	}
+	if auto <= 0 {
+		return 60 * time.Second
+	}
+	return auto
+}

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

@@ -0,0 +1,90 @@
+package cache
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestEffectiveL1TTL_ExplicitL1TTL(t *testing.T) {
+	ns := &NamespaceConfig{
+		L2TTL: 10 * time.Minute,
+		L1TTL: 45 * time.Second,
+	}
+	assert.Equal(t, 45*time.Second, ns.effectiveL1TTL(), "显式设置 L1TTL 时应直接使用")
+}
+
+func TestEffectiveL1TTL_AutoCalculation_Quarter(t *testing.T) {
+	// L2TTL/4 = 120s，边界值，结果应为 120s
+	ns := &NamespaceConfig{
+		L2TTL: 8 * time.Minute, // 480s / 4 = 120s
+	}
+	assert.Equal(t, 120*time.Second, ns.effectiveL1TTL())
+}
+
+func TestEffectiveL1TTL_AutoCalculation_CappedAt120s(t *testing.T) {
+	// L2TTL/4 > 120s 时，结果应被截断为 120s
+	ns := &NamespaceConfig{
+		L2TTL: time.Hour, // 3600s / 4 = 900s → capped to 120s
+	}
+	assert.Equal(t, 120*time.Second, ns.effectiveL1TTL())
+}
+
+func TestEffectiveL1TTL_AutoCalculation_BelowCap(t *testing.T) {
+	// L2TTL/4 < 120s 时，直接使用 L2TTL/4
+	ns := &NamespaceConfig{
+		L2TTL: 2 * time.Minute, // 120s / 4 = 30s
+	}
+	assert.Equal(t, 30*time.Second, ns.effectiveL1TTL())
+}
+
+func TestEffectiveL1TTL_ZeroL2TTL_Fallback(t *testing.T) {
+	// L2TTL=0 时 auto=0，应回退到 60s
+	ns := &NamespaceConfig{
+		L2TTL: 0,
+	}
+	assert.Equal(t, 60*time.Second, ns.effectiveL1TTL())
+}
+
+func TestEffectiveL1TTL_VerySmallL2TTL(t *testing.T) {
+	// L2TTL=1s → L2TTL/4=250ms，auto > 0，直接返回 250ms
+	ns := &NamespaceConfig{
+		L2TTL: time.Second,
+	}
+	assert.Equal(t, 250*time.Millisecond, ns.effectiveL1TTL())
+}
+
+func TestEffectiveL1TTL_Exactly120s(t *testing.T) {
+	// L2TTL/4 == 120s 时不应被截断（等于上限）
+	ns := &NamespaceConfig{
+		L2TTL: 480 * time.Second, // 480s / 4 = 120s
+	}
+	assert.Equal(t, 120*time.Second, ns.effectiveL1TTL())
+}
+
+func TestEffectiveL1TTL_JustAbove120s(t *testing.T) {
+	// L2TTL/4 = 121s，超过上限，截断为 120s
+	ns := &NamespaceConfig{
+		L2TTL: 484 * time.Second, // 484s / 4 = 121s
+	}
+	assert.Equal(t, 120*time.Second, ns.effectiveL1TTL())
+}
+
+func TestNamespaceConfig_DefaultFields(t *testing.T) {
+	ns := NamespaceConfig{
+		Name:  "test_ns",
+		L2TTL: 5 * time.Minute,
+	}
+	// 未显式设置时布尔字段为零值
+	assert.False(t, ns.L1Enabled)
+	assert.False(t, ns.Singleflight)
+	assert.Equal(t, SerializationFormat(""), ns.Serialization)
+}
+
+func TestNamespaceConfig_SerializationFormat(t *testing.T) {
+	ns := NamespaceConfig{
+		Serialization: SerializationJSON,
+	}
+	assert.Equal(t, SerializationJSON, ns.Serialization)
+}

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

@@ -0,0 +1,39 @@
+package cache
+
+import "time"
+
+// GetOption 单次 Get 操作的可选覆盖
+type GetOption func(*getOptions)
+
+type getOptions struct {
+	l2TTLOverride time.Duration
+	skipL1        bool
+	forceRefresh  bool
+}
+
+func defaultGetOptions() *getOptions {
+	return &getOptions{}
+}
+
+func applyGetOptions(opts []GetOption) *getOptions {
+	o := defaultGetOptions()
+	for _, opt := range opts {
+		opt(o)
+	}
+	return o
+}
+
+// WithL2TTL 覆盖本次操作的 L2 TTL
+func WithL2TTL(ttl time.Duration) GetOption {
+	return func(o *getOptions) { o.l2TTLOverride = ttl }
+}
+
+// WithSkipL1 跳过本次操作的 L1 缓存
+func WithSkipL1() GetOption {
+	return func(o *getOptions) { o.skipL1 = true }
+}
+
+// WithForceRefresh 强制从 source 重新加载（忽略缓存）
+func WithForceRefresh() GetOption {
+	return func(o *getOptions) { o.forceRefresh = true }
+}

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

@@ -0,0 +1,96 @@
+package cache
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestDefaultGetOptions(t *testing.T) {
+	o := defaultGetOptions()
+
+	assert.Equal(t, time.Duration(0), o.l2TTLOverride, "默认 l2TTLOverride 应为零值")
+	assert.False(t, o.skipL1, "默认 skipL1 应为 false")
+	assert.False(t, o.forceRefresh, "默认 forceRefresh 应为 false")
+}
+
+func TestApplyGetOptions_NoOptions(t *testing.T) {
+	o := applyGetOptions(nil)
+
+	assert.Equal(t, time.Duration(0), o.l2TTLOverride)
+	assert.False(t, o.skipL1)
+	assert.False(t, o.forceRefresh)
+}
+
+func TestApplyGetOptions_EmptySlice(t *testing.T) {
+	o := applyGetOptions([]GetOption{})
+
+	assert.Equal(t, time.Duration(0), o.l2TTLOverride)
+	assert.False(t, o.skipL1)
+	assert.False(t, o.forceRefresh)
+}
+
+func TestWithL2TTL(t *testing.T) {
+	o := applyGetOptions([]GetOption{WithL2TTL(5 * time.Minute)})
+
+	assert.Equal(t, 5*time.Minute, o.l2TTLOverride)
+	assert.False(t, o.skipL1)
+	assert.False(t, o.forceRefresh)
+}
+
+func TestWithL2TTL_Zero(t *testing.T) {
+	o := applyGetOptions([]GetOption{WithL2TTL(0)})
+
+	assert.Equal(t, time.Duration(0), o.l2TTLOverride)
+}
+
+func TestWithSkipL1(t *testing.T) {
+	o := applyGetOptions([]GetOption{WithSkipL1()})
+
+	assert.True(t, o.skipL1)
+	assert.Equal(t, time.Duration(0), o.l2TTLOverride)
+	assert.False(t, o.forceRefresh)
+}
+
+func TestWithForceRefresh(t *testing.T) {
+	o := applyGetOptions([]GetOption{WithForceRefresh()})
+
+	assert.True(t, o.forceRefresh)
+	assert.Equal(t, time.Duration(0), o.l2TTLOverride)
+	assert.False(t, o.skipL1)
+}
+
+func TestApplyGetOptions_AllOptions(t *testing.T) {
+	o := applyGetOptions([]GetOption{
+		WithL2TTL(10 * time.Second),
+		WithSkipL1(),
+		WithForceRefresh(),
+	})
+
+	assert.Equal(t, 10*time.Second, o.l2TTLOverride)
+	assert.True(t, o.skipL1)
+	assert.True(t, o.forceRefresh)
+}
+
+func TestApplyGetOptions_LastWriteWins(t *testing.T) {
+	// 同一选项多次设置，最后一次生效
+	o := applyGetOptions([]GetOption{
+		WithL2TTL(1 * time.Minute),
+		WithL2TTL(30 * time.Second),
+	})
+
+	assert.Equal(t, 30*time.Second, o.l2TTLOverride)
+}
+
+func TestApplyGetOptions_IndependentFromDefault(t *testing.T) {
+	// 每次 applyGetOptions 应返回独立的 options 实例，不共享状态
+	o1 := applyGetOptions([]GetOption{WithSkipL1()})
+	o2 := applyGetOptions([]GetOption{WithForceRefresh()})
+
+	assert.True(t, o1.skipL1)
+	assert.False(t, o1.forceRefresh)
+
+	assert.False(t, o2.skipL1)
+	assert.True(t, o2.forceRefresh)
+}