@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/queue/queue.go

@@ -0,0 +1,288 @@
+package queue
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/hibiken/asynq"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/config"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 队列名称
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	QueueNotification      = "notification"
+	QueueHelpdesk          = "helpdesk"
+	QueueAITask            = "ai-task"
+	QueueAnalysis          = "analysis"
+	QueueExport            = "export"
+	QueueMedia             = "media"
+	QueueCMS               = "cms"
+	QueueEvents            = "events"
+	QueueBilling           = "billing"
+	QueueKOLSearch         = "kol-search"
+	QueueKOLAnalysis       = "kol-analysis"
+	QueueWebhook           = "webhook"
+	QueuePromotion         = "promotion"
+	QueueCampaign          = "campaign"
+	QueueIntegrationEvents = "integration-events"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 任务类型
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	// 导出任务
+	JobExportGenerate = "export:generate"
+	JobExportCleanup  = "export:cleanup"
+
+	// 跨进程事件中继
+	JobEventRelay = "event:relay"
+
+	// Webhook 投递任务
+	JobWebhookDeliver = "webhook:deliver"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 入队选项
+// ═══════════════════════════════════════════════════════════════
+
+// EnqueueOptions 入队选项
+type EnqueueOptions struct {
+	// 队列名称
+	Queue string
+	// 最大重试次数
+	MaxRetry *int
+	// 任务超时
+	Timeout time.Duration
+	// 延迟执行
+	Delay time.Duration
+	// 指定执行时间
+	ProcessAt time.Time
+	// 相同任务类型、队列与载荷的有界唯一窗口
+	UniqueTTL time.Duration
+}
+
+type asynqClient interface {
+	EnqueueContext(context.Context, *asynq.Task, ...asynq.Option) (*asynq.TaskInfo, error)
+	Close() error
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 客户端（生产者）
+// ═══════════════════════════════════════════════════════════════
+
+// Client 任务队列客户端（入队端）
+type Client struct {
+	client asynqClient
+	logger *zap.Logger
+}
+
+// NewClient 创建 Asynq 客户端
+func NewClient(cfg *config.RedisConfig, logger *zap.Logger) (*Client, error) {
+	redisOpt := asynq.RedisClientOpt{
+		Addr:     fmt.Sprintf("%s:%d", cfg.Host, cfg.Port),
+		Password: cfg.Password,
+		DB:       cfg.DB,
+	}
+
+	client := asynq.NewClient(redisOpt)
+
+	return &Client{
+		client: client,
+		logger: logger.Named("QueueClient"),
+	}, nil
+}
+
+// Close 关闭客户端
+func (c *Client) Close() error {
+	return c.client.Close()
+}
+
+// Enqueue 入队任务
+func (c *Client) Enqueue(ctx context.Context, jobType string, payload any, opts ...EnqueueOptions) (*asynq.TaskInfo, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return nil, fmt.Errorf("marshal payload: %w", err)
+	}
+
+	task := asynq.NewTask(jobType, data)
+
+	// 构建 asynq 选项
+	asynqOpts := c.buildOptions(opts...)
+
+	info, err := c.client.EnqueueContext(ctx, task, asynqOpts...)
+	if err != nil {
+		c.logger.Error("enqueue failed",
+			zap.String("jobType", jobType),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("enqueue task: %w", err)
+	}
+
+	c.logger.Debug("task enqueued",
+		zap.String("taskId", info.ID),
+		zap.String("jobType", jobType),
+		zap.String("queue", info.Queue),
+	)
+
+	return info, nil
+}
+
+// EnqueueIn 延迟入队
+func (c *Client) EnqueueIn(ctx context.Context, jobType string, delay time.Duration, payload any, opts ...EnqueueOptions) (*asynq.TaskInfo, error) {
+	var opt EnqueueOptions
+	if len(opts) > 0 {
+		opt = opts[0]
+	}
+	opt.Delay = delay
+	return c.Enqueue(ctx, jobType, payload, opt)
+}
+
+func (c *Client) buildOptions(opts ...EnqueueOptions) []asynq.Option {
+	var asynqOpts []asynq.Option
+
+	if len(opts) == 0 {
+		return asynqOpts
+	}
+
+	opt := opts[0]
+
+	if opt.Queue != "" {
+		asynqOpts = append(asynqOpts, asynq.Queue(opt.Queue))
+	}
+
+	if opt.MaxRetry != nil {
+		asynqOpts = append(asynqOpts, asynq.MaxRetry(*opt.MaxRetry))
+	}
+
+	if opt.Timeout > 0 {
+		asynqOpts = append(asynqOpts, asynq.Timeout(opt.Timeout))
+	}
+
+	if opt.Delay > 0 {
+		asynqOpts = append(asynqOpts, asynq.ProcessIn(opt.Delay))
+	}
+
+	if !opt.ProcessAt.IsZero() {
+		asynqOpts = append(asynqOpts, asynq.ProcessAt(opt.ProcessAt))
+	}
+
+	if opt.UniqueTTL > 0 {
+		asynqOpts = append(asynqOpts, asynq.Unique(opt.UniqueTTL))
+	}
+
+	return asynqOpts
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 服务端（消费者）
+// ═══════════════════════════════════════════════════════════════
+
+// Server 任务队列服务端（消费端）
+type Server struct {
+	server *asynq.Server
+	mux    *asynq.ServeMux
+	logger *zap.Logger
+}
+
+// NewServer 创建 Asynq 服务端
+func NewServer(cfg *config.RedisConfig, logger *zap.Logger, concurrency ...int) (*Server, error) {
+	redisOpt := asynq.RedisClientOpt{
+		Addr:     fmt.Sprintf("%s:%d", cfg.Host, cfg.Port),
+		Password: cfg.Password,
+		DB:       cfg.DB,
+	}
+
+	// 默认并发数
+	conc := 10
+	if len(concurrency) > 0 && concurrency[0] > 0 {
+		conc = concurrency[0]
+	}
+
+	srv := asynq.NewServer(redisOpt, asynq.Config{
+		Concurrency: conc,
+		Queues: map[string]int{
+			QueueNotification:      6,
+			QueueEvents:            4,
+			QueueWebhook:           4,
+			QueueHelpdesk:          3,
+			QueueMedia:             2,
+			QueueAITask:            2,
+			QueueExport:            2,
+			QueueCMS:               2,
+			QueueKOLSearch:         2,
+			QueueKOLAnalysis:       1,
+			QueueAnalysis:          1,
+			QueueBilling:           3,
+			QueuePromotion:         2,
+			QueueCampaign:          3,
+			QueueIntegrationEvents: 3,
+		},
+		RetryDelayFunc: func(n int, _ error, _ *asynq.Task) time.Duration {
+			// 指数退避：2s * 2^n
+			return time.Duration(2<<uint(n)) * time.Second //nolint:gosec // G115: n 由 Asynq MaxRetry 限制，不会溢出
+		},
+		Logger: newZapAdapter(logger),
+	})
+
+	return &Server{
+		server: srv,
+		mux:    asynq.NewServeMux(),
+		logger: logger.Named("QueueServer"),
+	}, nil
+}
+
+// Handle 注册任务处理器
+func (s *Server) Handle(jobType string, handler asynq.Handler) {
+	s.mux.Handle(jobType, handler)
+	s.logger.Info("task handler registered", zap.String("jobType", jobType))
+}
+
+// HandleFunc 注册任务处理函数
+func (s *Server) HandleFunc(jobType string, handler func(context.Context, *asynq.Task) error) {
+	s.mux.HandleFunc(jobType, handler)
+	s.logger.Info("task handler registered", zap.String("jobType", jobType))
+}
+
+// Use 添加中间件到任务处理链
+func (s *Server) Use(mws ...asynq.MiddlewareFunc) {
+	s.mux.Use(mws...)
+}
+
+// Start 启动消费服务
+func (s *Server) Start() error {
+	s.logger.Info("starting queue server")
+	return s.server.Start(s.mux)
+}
+
+// Shutdown 优雅关闭消费服务
+func (s *Server) Shutdown() {
+	s.server.Shutdown()
+	s.logger.Info("queue server stopped")
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Zap 日志适配器
+// ═══════════════════════════════════════════════════════════════
+
+type zapAdapter struct {
+	logger *zap.SugaredLogger
+}
+
+func newZapAdapter(logger *zap.Logger) *zapAdapter {
+	return &zapAdapter{logger: logger.Named("Asynq").Sugar()}
+}
+
+func (a *zapAdapter) Debug(args ...any) { a.logger.Debug(args...) }
+func (a *zapAdapter) Info(args ...any)  { a.logger.Info(args...) }
+func (a *zapAdapter) Warn(args ...any)  { a.logger.Warn(args...) }
+func (a *zapAdapter) Error(args ...any) { a.logger.Error(args...) }
+func (a *zapAdapter) Fatal(args ...any) { a.logger.Fatal(args...) }

package/dist/resources/templates/go-backend/internal/core/queue/queue_test.go

@@ -0,0 +1,159 @@
+package queue
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/hibiken/asynq"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+)
+
+type recordedEnqueue struct {
+	jobType string
+	payload []byte
+	options map[asynq.OptionType]any
+}
+
+type recordingAsynqClient struct {
+	uniqueTasks map[string]struct{}
+	calls       []recordedEnqueue
+}
+
+func newRecordingAsynqClient() *recordingAsynqClient {
+	return &recordingAsynqClient{uniqueTasks: make(map[string]struct{})}
+}
+
+func (c *recordingAsynqClient) EnqueueContext(
+	_ context.Context,
+	task *asynq.Task,
+	options ...asynq.Option,
+) (*asynq.TaskInfo, error) {
+	recorded := recordedEnqueue{
+		jobType: task.Type(),
+		payload: task.Payload(),
+		options: make(map[asynq.OptionType]any, len(options)),
+	}
+	for _, option := range options {
+		recorded.options[option.Type()] = option.Value()
+	}
+	c.calls = append(c.calls, recorded)
+
+	queueName, _ := recorded.options[asynq.QueueOpt].(string)
+	if queueName == "" {
+		queueName = "default"
+	}
+	if _, unique := recorded.options[asynq.UniqueOpt]; unique {
+		identity := queueName + "\x00" + task.Type() + "\x00" + string(task.Payload())
+		if _, exists := c.uniqueTasks[identity]; exists {
+			return nil, asynq.ErrDuplicateTask
+		}
+		c.uniqueTasks[identity] = struct{}{}
+	}
+
+	return &asynq.TaskInfo{
+		ID:      fmt.Sprintf("generated-%d", len(c.calls)),
+		Queue:   queueName,
+		Type:    task.Type(),
+		Payload: task.Payload(),
+	}, nil
+}
+
+func (c *recordingAsynqClient) Close() error {
+	return nil
+}
+
+func TestClientEnqueueUniqueTTLRejectsSamePayload(t *testing.T) {
+	asynqClient := newRecordingAsynqClient()
+	client := &Client{client: asynqClient, logger: zap.NewNop()}
+	options := EnqueueOptions{Queue: QueueBilling, UniqueTTL: 5 * time.Minute}
+	payload := map[string]any{"operation_no": "operation-1", "claim_id": 19}
+
+	_, err := client.Enqueue(t.Context(), "store-purchase-reconcile", payload, options)
+	require.NoError(t, err)
+	_, err = client.Enqueue(t.Context(), "store-purchase-reconcile", payload, options)
+	require.ErrorIs(t, err, asynq.ErrDuplicateTask)
+	require.Len(t, asynqClient.calls, 2)
+}
+
+func TestClientEnqueueUniqueTTLAllowsDifferentPayload(t *testing.T) {
+	asynqClient := newRecordingAsynqClient()
+	client := &Client{client: asynqClient, logger: zap.NewNop()}
+	options := EnqueueOptions{Queue: QueueBilling, UniqueTTL: 5 * time.Minute}
+
+	first, err := client.Enqueue(t.Context(), "store-purchase-reconcile", map[string]any{
+		"operation_no": "operation-1",
+		"claim_id":     19,
+	}, options)
+	require.NoError(t, err)
+	second, err := client.Enqueue(t.Context(), "store-purchase-reconcile", map[string]any{
+		"operation_no": "operation-2",
+		"claim_id":     19,
+	}, options)
+	require.NoError(t, err)
+	require.NotEqual(t, first.ID, second.ID)
+}
+
+func TestClientEnqueueWithoutUniqueTTLDoesNotDeduplicate(t *testing.T) {
+	asynqClient := newRecordingAsynqClient()
+	client := &Client{client: asynqClient, logger: zap.NewNop()}
+	options := EnqueueOptions{Queue: QueueBilling}
+	payload := map[string]int{"claim_id": 19}
+
+	_, err := client.Enqueue(t.Context(), "store-purchase-reconcile", payload, options)
+	require.NoError(t, err)
+	_, err = client.Enqueue(t.Context(), "store-purchase-reconcile", payload, options)
+	require.NoError(t, err)
+	require.Len(t, asynqClient.calls, 2)
+}
+
+func TestClientBuildOptionsIgnoresNonPositiveUniqueTTL(t *testing.T) {
+	client := &Client{}
+	for _, ttl := range []time.Duration{0, -time.Minute} {
+		options := client.buildOptions(EnqueueOptions{UniqueTTL: ttl})
+		values := make(map[asynq.OptionType]any, len(options))
+		for _, option := range options {
+			values[option.Type()] = option.Value()
+		}
+		require.NotContains(t, values, asynq.UniqueOpt)
+	}
+}
+
+func TestClientEnqueueUniqueTTLAllowsNextRetryAttempt(t *testing.T) {
+	asynqClient := newRecordingAsynqClient()
+	client := &Client{client: asynqClient, logger: zap.NewNop()}
+	options := EnqueueOptions{Queue: QueueWebhook, UniqueTTL: 5 * time.Minute}
+
+	_, err := client.Enqueue(t.Context(), "payment:webhook_process", struct {
+		EventID int64 `json:"event_id"`
+		Attempt int   `json:"attempt"`
+	}{EventID: 19, Attempt: 0}, options)
+	require.NoError(t, err)
+	_, err = client.Enqueue(t.Context(), "payment:webhook_process", struct {
+		EventID int64 `json:"event_id"`
+		Attempt int   `json:"attempt"`
+	}{EventID: 19, Attempt: 1}, options)
+	require.NoError(t, err)
+}
+
+func TestClientBuildOptionsUsesBoundedPayloadUniquenessWithoutArchivedTaskIdentity(t *testing.T) {
+	client := &Client{}
+	ttl := 7 * time.Minute
+	options := client.buildOptions(EnqueueOptions{
+		Queue:     QueueBilling,
+		UniqueTTL: ttl,
+	})
+
+	values := make(map[asynq.OptionType]any, len(options))
+	for _, option := range options {
+		values[option.Type()] = option.Value()
+	}
+	require.Equal(t, QueueBilling, values[asynq.QueueOpt])
+	require.Equal(t, ttl, values[asynq.UniqueOpt])
+	require.NotContains(t, values, asynq.TaskIDOpt)
+	require.NotContains(t, values, asynq.RetentionOpt)
+}
+
+var _ asynqClient = (*recordingAsynqClient)(nil)