@stackonward/cli 0.0.1 → 1.0.1

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

@@ -0,0 +1,311 @@
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+
+	"{{module}}/internal/core/config"
+)
+
+// RedisService Redis 客户端封装
+type RedisService struct {
+	client *redis.Client
+}
+
+// NewRedisService 创建 Redis 服务
+func NewRedisService(cfg *config.RedisConfig) (*RedisService, error) {
+	client := redis.NewClient(&redis.Options{
+		Addr:            fmt.Sprintf("%s:%d", cfg.Host, cfg.Port),
+		Password:        cfg.Password,
+		DB:              cfg.DB,
+		MaxRetries:      3,
+		MinRetryBackoff: 200 * time.Millisecond,
+		MaxRetryBackoff: 2 * time.Second,
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err := client.Ping(ctx).Err(); err != nil {
+		return nil, errors.Join(fmt.Errorf("connect redis: %w", err), client.Close())
+	}
+
+	return &RedisService{client: client}, nil
+}
+
+// Close 关闭连接
+func (s *RedisService) Close() error {
+	return s.client.Close()
+}
+
+// Client 获取底层 Redis 客户端
+func (s *RedisService) Client() *redis.Client {
+	return s.client
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 基础操作
+// ═══════════════════════════════════════════════════════════════
+
+// Get 获取字符串值
+func (s *RedisService) Get(ctx context.Context, key string) (string, error) {
+	val, err := s.client.Get(ctx, key).Result()
+	if errors.Is(err, redis.Nil) {
+		return "", nil
+	}
+	return val, err
+}
+
+// Set 设置字符串值
+func (s *RedisService) Set(ctx context.Context, key, value string, ttl ...time.Duration) error {
+	var expiration time.Duration
+	if len(ttl) > 0 {
+		expiration = ttl[0]
+	}
+	return s.client.Set(ctx, key, value, expiration).Err()
+}
+
+// Del 删除键
+func (s *RedisService) Del(ctx context.Context, key string) error {
+	return s.client.Del(ctx, key).Err()
+}
+
+// Exists 检查键是否存在
+func (s *RedisService) Exists(ctx context.Context, key string) (bool, error) {
+	n, err := s.client.Exists(ctx, key).Result()
+	return n == 1, err
+}
+
+// TTL 获取键的剩余过期时间
+func (s *RedisService) TTL(ctx context.Context, key string) (time.Duration, error) {
+	return s.client.TTL(ctx, key).Result()
+}
+
+// Expire 设置键的过期时间
+func (s *RedisService) Expire(ctx context.Context, key string, ttl time.Duration) error {
+	return s.client.Expire(ctx, key, ttl).Err()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// JSON 操作
+// ═══════════════════════════════════════════════════════════════
+
+// GetJSON 获取并反序列化 JSON
+func (s *RedisService) GetJSON(ctx context.Context, key string, dest any) error {
+	val, err := s.client.Get(ctx, key).Result()
+	if errors.Is(err, redis.Nil) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal([]byte(val), dest)
+}
+
+// SetJSON 序列化并存储 JSON
+func (s *RedisService) SetJSON(ctx context.Context, key string, value any, ttl ...time.Duration) error {
+	data, err := json.Marshal(value)
+	if err != nil {
+		return fmt.Errorf("marshal json: %w", err)
+	}
+	var expiration time.Duration
+	if len(ttl) > 0 {
+		expiration = ttl[0]
+	}
+	return s.client.Set(ctx, key, data, expiration).Err()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Hash 操作
+// ═══════════════════════════════════════════════════════════════
+
+// HGet 获取 Hash 字段值
+func (s *RedisService) HGet(ctx context.Context, key, field string) (string, error) {
+	val, err := s.client.HGet(ctx, key, field).Result()
+	if errors.Is(err, redis.Nil) {
+		return "", nil
+	}
+	return val, err
+}
+
+// HSet 设置 Hash 字段值
+func (s *RedisService) HSet(ctx context.Context, key, field, value string) error {
+	return s.client.HSet(ctx, key, field, value).Err()
+}
+
+// HDel 删除 Hash 字段
+func (s *RedisService) HDel(ctx context.Context, key, field string) error {
+	return s.client.HDel(ctx, key, field).Err()
+}
+
+// HGetAll 获取 Hash 所有字段
+func (s *RedisService) HGetAll(ctx context.Context, key string) (map[string]string, error) {
+	return s.client.HGetAll(ctx, key).Result()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Set 操作
+// ═══════════════════════════════════════════════════════════════
+
+// SAdd 添加集合成员
+func (s *RedisService) SAdd(ctx context.Context, key string, members ...any) (int64, error) {
+	return s.client.SAdd(ctx, key, members...).Result()
+}
+
+// SRem 移除集合成员
+func (s *RedisService) SRem(ctx context.Context, key string, members ...any) (int64, error) {
+	return s.client.SRem(ctx, key, members...).Result()
+}
+
+// SIsMember 判断是否是集合成员
+func (s *RedisService) SIsMember(ctx context.Context, key string, member any) (bool, error) {
+	return s.client.SIsMember(ctx, key, member).Result()
+}
+
+// SMembers 获取集合所有成员
+func (s *RedisService) SMembers(ctx context.Context, key string) ([]string, error) {
+	return s.client.SMembers(ctx, key).Result()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 原子写操作
+// ═══════════════════════════════════════════════════════════════
+
+// SetNX 仅在键不存在时设置值（原子操作）
+func (s *RedisService) SetNX(ctx context.Context, key, value string, ttl time.Duration) (bool, error) {
+	return s.client.SetNX(ctx, key, value, ttl).Result() //nolint:staticcheck // SA1019: SetNX 功能等价于 SetArgs(NX)，待 go-redis 移除后再迁移
+}
+
+// GetBytes 获取原始字节值（redis.Nil 时返回 nil, nil）
+func (s *RedisService) GetBytes(ctx context.Context, key string) ([]byte, error) {
+	val, err := s.client.Get(ctx, key).Bytes()
+	if errors.Is(err, redis.Nil) {
+		return nil, nil
+	}
+	return val, err
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Hash 批量操作
+// ═══════════════════════════════════════════════════════════════
+
+// HSetMap 批量设置 Hash 字段
+func (s *RedisService) HSetMap(ctx context.Context, key string, fields map[string]any) error {
+	return s.client.HSet(ctx, key, fields).Err()
+}
+
+// HSetMapWithTTL 批量设置 Hash 字段并设置过期时间（Pipeline 保证原子执行）
+func (s *RedisService) HSetMapWithTTL(ctx context.Context, key string, fields map[string]any, ttl time.Duration) error {
+	pipe := s.client.Pipeline()
+	pipe.HSet(ctx, key, fields)
+	pipe.Expire(ctx, key, ttl)
+	_, err := pipe.Exec(ctx)
+	return err
+}
+
+// hReplaceMapScript Lua 脚本：原子替换 Hash 全部字段
+//
+// KEYS[1] = hash key
+// ARGV[1] = TTL (seconds)
+// ARGV[2..n] = field1, value1, field2, value2, ...
+var hReplaceMapScript = `
+redis.call("DEL", KEYS[1])
+if #ARGV > 1 then
+    redis.call("HSET", KEYS[1], unpack(ARGV, 2))
+end
+redis.call("EXPIRE", KEYS[1], ARGV[1])
+return 1
+`
+
+// HReplaceMapWithTTL 原子替换 Hash 全部字段（Lua 脚本保证原子性）
+//
+// 使用 Lua 脚本在 Redis 服务端原子执行 DEL → HSET → EXPIRE，
+// 消除 Pipeline 方式下 DEL 和 HSET 之间的读空窗口。
+func (s *RedisService) HReplaceMapWithTTL(ctx context.Context, key string, fields map[string]string, ttl time.Duration) error {
+	args := make([]any, 0, 1+len(fields)*2)
+	args = append(args, int(ttl.Seconds()))
+	for field, val := range fields {
+		args = append(args, field, val)
+	}
+	return s.client.Eval(ctx, hReplaceMapScript, []string{key}, args...).Err()
+}
+
+// HIncrBy 递增 Hash 字段的整数值
+func (s *RedisService) HIncrBy(ctx context.Context, key, field string, incr int64) (int64, error) {
+	return s.client.HIncrBy(ctx, key, field, incr).Result()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Key 扫描
+// ═══════════════════════════════════════════════════════════════
+
+// ScanKeys 使用 SCAN 命令迭代匹配 pattern 的所有键
+// batchSize 控制每次 SCAN 返回的建议数量。返回所有匹配的键。
+func (s *RedisService) ScanKeys(ctx context.Context, pattern string, batchSize int64) ([]string, error) {
+	var keys []string
+	iter := s.client.Scan(ctx, 0, pattern, batchSize).Iterator()
+	for iter.Next(ctx) {
+		keys = append(keys, iter.Val())
+	}
+	if err := iter.Err(); err != nil {
+		return nil, err
+	}
+	return keys, nil
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 简易锁
+// ═══════════════════════════════════════════════════════════════
+
+// AcquireLock 获取简易分布式锁
+func (s *RedisService) AcquireLock(ctx context.Context, key string, ttl time.Duration) (string, error) {
+	lockValue := fmt.Sprintf("%d-%d", time.Now().UnixNano(), time.Now().UnixMicro()%1000000)
+	ok, err := s.client.SetNX(ctx, key, lockValue, ttl).Result() //nolint:staticcheck // SA1019: SetNX 功能等价于 SetArgs(NX)，待 go-redis 移除后再迁移
+	if err != nil {
+		return "", err
+	}
+	if !ok {
+		return "", nil
+	}
+	return lockValue, nil
+}
+
+// ReleaseLock 释放简易分布式锁
+func (s *RedisService) ReleaseLock(ctx context.Context, key, lockValue string) (bool, error) {
+	script := `
+		if redis.call("get", KEYS[1]) == ARGV[1] then
+			return redis.call("del", KEYS[1])
+		else
+			return 0
+		end
+	`
+	result, err := s.client.Eval(ctx, script, []string{key}, lockValue).Int64()
+	if err != nil {
+		return false, err
+	}
+	return result == 1, nil
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 计数器
+// ═══════════════════════════════════════════════════════════════
+
+// Incr 自增
+func (s *RedisService) Incr(ctx context.Context, key string) (int64, error) {
+	return s.client.Incr(ctx, key).Result()
+}
+
+// IncrBy 增加指定值
+func (s *RedisService) IncrBy(ctx context.Context, key string, value int64) (int64, error) {
+	return s.client.IncrBy(ctx, key, value).Result()
+}
+
+// Decr 自减
+func (s *RedisService) Decr(ctx context.Context, key string) (int64, error) {
+	return s.client.Decr(ctx, key).Result()
+}

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

@@ -0,0 +1,51 @@
+package cache
+
+import (
+	"bufio"
+	"fmt"
+	"net"
+	"strconv"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"{{module}}/internal/core/config"
+)
+
+func TestNewRedisServiceClosesConnectionWhenPingFails(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+	defer listener.Close()
+	closed := make(chan struct{})
+	go func() {
+		defer close(closed)
+		conn, err := listener.Accept()
+		if err != nil {
+			return
+		}
+		defer conn.Close()
+		_ = conn.SetDeadline(time.Now().Add(8 * time.Second))
+		reader := bufio.NewReader(conn)
+		for {
+			line, err := reader.ReadString('\n')
+			if err != nil {
+				return
+			}
+			if len(line) > 0 && line[0] == '*' {
+				_, _ = fmt.Fprint(conn, "-ERR unsupported command\r\n")
+			}
+		}
+	}()
+	host, portText, err := net.SplitHostPort(listener.Addr().String())
+	require.NoError(t, err)
+	port, err := strconv.Atoi(portText)
+	require.NoError(t, err)
+	service, err := NewRedisService(&config.RedisConfig{Host: host, Port: port})
+	require.Error(t, err)
+	require.Nil(t, service)
+	select {
+	case <-closed:
+	case <-time.After(time.Second):
+		t.Fatal("failed Redis constructor left its connection open")
+	}
+}

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

@@ -0,0 +1,31 @@
+package cache
+
+import "encoding/json"
+
+// Serializer 缓存值序列化接口
+type Serializer interface {
+	// Marshal 将值序列化为字节
+	Marshal(v any) ([]byte, error)
+	// Unmarshal 将字节反序列化到目标
+	Unmarshal(data []byte, dest any) error
+	// Format 返回序列化格式标识
+	Format() SerializationFormat
+}
+
+// JSONSerializer JSON 序列化器
+type JSONSerializer struct{}
+
+// Marshal 序列化
+func (s *JSONSerializer) Marshal(v any) ([]byte, error) {
+	return json.Marshal(v)
+}
+
+// Unmarshal 反序列化
+func (s *JSONSerializer) Unmarshal(data []byte, dest any) error {
+	return json.Unmarshal(data, dest)
+}
+
+// Format 格式标识
+func (s *JSONSerializer) Format() SerializationFormat {
+	return SerializationJSON
+}

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

@@ -0,0 +1,139 @@
+package cache
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestJSONSerializer_Format(t *testing.T) {
+	s := &JSONSerializer{}
+	assert.Equal(t, SerializationJSON, s.Format())
+}
+
+func TestJSONSerializer_MarshalUnmarshal_String(t *testing.T) {
+	s := &JSONSerializer{}
+
+	original := "hello cache"
+	data, err := s.Marshal(original)
+	require.NoError(t, err)
+
+	var result string
+	require.NoError(t, s.Unmarshal(data, &result))
+	assert.Equal(t, original, result)
+}
+
+func TestJSONSerializer_MarshalUnmarshal_Int(t *testing.T) {
+	s := &JSONSerializer{}
+
+	original := 12345
+	data, err := s.Marshal(original)
+	require.NoError(t, err)
+
+	var result int
+	require.NoError(t, s.Unmarshal(data, &result))
+	assert.Equal(t, original, result)
+}
+
+func TestJSONSerializer_MarshalUnmarshal_Struct(t *testing.T) {
+	type User struct {
+		ID   int64  `json:"id"`
+		Name string `json:"name"`
+	}
+
+	s := &JSONSerializer{}
+
+	original := User{ID: 99, Name: "Alice"}
+	data, err := s.Marshal(original)
+	require.NoError(t, err)
+
+	var result User
+	require.NoError(t, s.Unmarshal(data, &result))
+	assert.Equal(t, original, result)
+}
+
+func TestJSONSerializer_MarshalUnmarshal_Slice(t *testing.T) {
+	s := &JSONSerializer{}
+
+	original := []int{1, 2, 3, 4, 5}
+	data, err := s.Marshal(original)
+	require.NoError(t, err)
+
+	var result []int
+	require.NoError(t, s.Unmarshal(data, &result))
+	assert.Equal(t, original, result)
+}
+
+func TestJSONSerializer_MarshalUnmarshal_Map(t *testing.T) {
+	s := &JSONSerializer{}
+
+	original := map[string]any{"key": "value", "count": float64(42)}
+	data, err := s.Marshal(original)
+	require.NoError(t, err)
+
+	var result map[string]any
+	require.NoError(t, s.Unmarshal(data, &result))
+	assert.Equal(t, original, result)
+}
+
+func TestJSONSerializer_MarshalUnmarshal_Bool(t *testing.T) {
+	s := &JSONSerializer{}
+
+	for _, original := range []bool{true, false} {
+		data, err := s.Marshal(original)
+		require.NoError(t, err)
+
+		var result bool
+		require.NoError(t, s.Unmarshal(data, &result))
+		assert.Equal(t, original, result)
+	}
+}
+
+func TestJSONSerializer_MarshalUnmarshal_Nil(t *testing.T) {
+	s := &JSONSerializer{}
+
+	data, err := s.Marshal(nil)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("null"), data)
+}
+
+func TestJSONSerializer_UnmarshalInvalidJSON(t *testing.T) {
+	s := &JSONSerializer{}
+
+	var result string
+	err := s.Unmarshal([]byte("{invalid json}"), &result)
+	assert.Error(t, err, "无效 JSON 应返回错误")
+}
+
+func TestJSONSerializer_MarshalUnmarshal_NestedStruct(t *testing.T) {
+	type Address struct {
+		City    string `json:"city"`
+		Country string `json:"country"`
+	}
+	type Profile struct {
+		ID      int64    `json:"id"`
+		Address Address  `json:"address"`
+		Tags    []string `json:"tags"`
+	}
+
+	s := &JSONSerializer{}
+
+	original := Profile{
+		ID:      1,
+		Address: Address{City: "Shanghai", Country: "CN"},
+		Tags:    []string{"admin", "user"},
+	}
+
+	data, err := s.Marshal(original)
+	require.NoError(t, err)
+
+	var result Profile
+	require.NoError(t, s.Unmarshal(data, &result))
+	assert.Equal(t, original, result)
+}
+
+func TestJSONSerializer_ImplementsInterface(t *testing.T) {
+	// 编译期验证 *JSONSerializer 实现了 Serializer 接口
+	var _ Serializer = (*JSONSerializer)(nil)
+}

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

@@ -0,0 +1,53 @@
+package cache
+
+import "sync"
+
+// singleflightCall 正在进行或已完成的调用
+type singleflightCall struct {
+	wg  sync.WaitGroup
+	val any
+	err error
+	// dups 记录共享此调用结果的请求数
+	dups int
+}
+
+// singleflightGroup 避免重复执行相同操作的去重机制
+//
+// 当多个 goroutine 同时请求相同的缓存键时，
+// 只有第一个请求会实际执行 loader，其余请求等待并共享结果。
+type singleflightGroup struct {
+	mu sync.Mutex
+	m  map[string]*singleflightCall
+}
+
+// do 执行给定函数，保证同一 key 同一时刻只有一个函数在执行。
+// 返回值、错误和是否共享结果。
+//
+//nolint:revive // error-return: 签名与 golang.org/x/sync/singleflight.Group.Do 保持一致
+func (g *singleflightGroup) do(key string, fn func() (any, error)) (any, error, bool) {
+	g.mu.Lock()
+	if g.m == nil {
+		g.m = make(map[string]*singleflightCall)
+	}
+
+	if c, ok := g.m[key]; ok {
+		c.dups++
+		g.mu.Unlock()
+		c.wg.Wait()
+		return c.val, c.err, true
+	}
+
+	c := &singleflightCall{}
+	c.wg.Add(1)
+	g.m[key] = c
+	g.mu.Unlock()
+
+	c.val, c.err = fn()
+	c.wg.Done()
+
+	g.mu.Lock()
+	delete(g.m, key)
+	g.mu.Unlock()
+
+	return c.val, c.err, c.dups > 0
+}