@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/common/validator/validator.go

@@ -0,0 +1,136 @@
+package validator
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"reflect"
+	"strings"
+	"sync"
+
+	"github.com/gin-gonic/gin"
+	"github.com/gin-gonic/gin/binding"
+	"github.com/go-playground/validator/v10"
+)
+
+var (
+	setupOnce sync.Once
+	setupErr  error
+)
+
+// Setup 注册自定义校验 tag 并配置 JSON 字段名
+func Setup() error {
+	setupOnce.Do(func() {
+		v, ok := binding.Validator.Engine().(*validator.Validate)
+		if !ok {
+			return
+		}
+
+		// 使用 JSON tag 作为字段名，与 NestJS 的 DTO 属性名保持一致
+		v.RegisterTagNameFunc(func(fld reflect.StructField) string {
+			name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
+			if name == "-" {
+				return ""
+			}
+			return name
+		})
+
+		// 注册自定义校验规则
+		setupErr = v.RegisterValidation("notblank", notBlank)
+	})
+	return setupErr
+}
+
+// notBlank 非空白字符串校验，排除纯空格的字符串
+func notBlank(fl validator.FieldLevel) bool {
+	field := fl.Field()
+	if field.Kind() != reflect.String {
+		return true
+	}
+	return strings.TrimSpace(field.String()) != ""
+}
+
+// BindJSONStrict 严格绑定 JSON，请求体中出现未知字段时直接报错。
+func BindJSONStrict(c *gin.Context, target any) error {
+	if err := Setup(); err != nil {
+		return fmt.Errorf("initialize request validator: %w", err)
+	}
+	body, err := io.ReadAll(c.Request.Body)
+	if err != nil {
+		return err
+	}
+	if err := RejectDuplicateJSONFields(body); err != nil {
+		return err
+	}
+	decoder := json.NewDecoder(bytes.NewReader(body))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(target); err != nil {
+		return err
+	}
+	if err := decoder.Decode(&struct{}{}); err != nil && !errors.Is(err, io.EOF) {
+		return err
+	}
+	return binding.Validator.ValidateStruct(target)
+}
+
+// RejectDuplicateJSONFields 校验单个 JSON 值并拒绝任意层级的重复对象字段。
+func RejectDuplicateJSONFields(body []byte) error {
+	decoder := json.NewDecoder(bytes.NewReader(body))
+	decoder.UseNumber()
+	if err := scanJSONValue(decoder); err != nil {
+		return err
+	}
+	if _, err := decoder.Token(); !errors.Is(err, io.EOF) {
+		if err == nil {
+			return errors.New("request body must contain one JSON value")
+		}
+		return err
+	}
+	return nil
+}
+
+func scanJSONValue(decoder *json.Decoder) error {
+	token, err := decoder.Token()
+	if err != nil {
+		return err
+	}
+	delimiter, ok := token.(json.Delim)
+	if !ok {
+		return nil
+	}
+	switch delimiter {
+	case '{':
+		seen := make(map[string]struct{})
+		for decoder.More() {
+			keyToken, err := decoder.Token()
+			if err != nil {
+				return err
+			}
+			key, ok := keyToken.(string)
+			if !ok {
+				return errors.New("JSON object key must be a string")
+			}
+			if _, duplicate := seen[key]; duplicate {
+				return fmt.Errorf("duplicate JSON field %q", key)
+			}
+			seen[key] = struct{}{}
+			if err := scanJSONValue(decoder); err != nil {
+				return err
+			}
+		}
+		_, err = decoder.Token()
+		return err
+	case '[':
+		for decoder.More() {
+			if err := scanJSONValue(decoder); err != nil {
+				return err
+			}
+		}
+		_, err = decoder.Token()
+		return err
+	default:
+		return errors.New("unexpected JSON delimiter")
+	}
+}

package/dist/resources/templates/go-backend/internal/common/validator/validator_test.go

@@ -0,0 +1,240 @@
+package validator
+
+import (
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/gin-gonic/gin/binding"
+	playgroundvalidator "github.com/go-playground/validator/v10"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func init() {
+	gin.SetMode(gin.TestMode)
+}
+
+// TestSetup 验证 Setup 注册成功且不返回错误
+func TestSetup(t *testing.T) {
+	err := Setup()
+	require.NoError(t, err, "Setup() 不应返回错误")
+}
+
+// TestSetup_Idempotent 验证多次调用 Setup 不会 panic 或报错
+func TestSetup_Idempotent(t *testing.T) {
+	for i := 0; i < 3; i++ {
+		err := Setup()
+		require.NoError(t, err, "第 %d 次 Setup() 不应返回错误", i+1)
+	}
+}
+
+// TestNotBlank_ViaGinBinding 通过 gin binding 验证 notblank tag 的行为
+func TestNotBlank_ViaGinBinding(t *testing.T) {
+	require.NoError(t, Setup())
+
+	tests := []struct {
+		name      string
+		value     string
+		wantValid bool
+	}{
+		{
+			name:      "普通字符串应通过",
+			value:     "hello",
+			wantValid: true,
+		},
+		{
+			name:      "带空格的正常字符串应通过",
+			value:     "  hello  ",
+			wantValid: true,
+		},
+		{
+			name:      "纯空格应被拒绝",
+			value:     "   ",
+			wantValid: false,
+		},
+		{
+			name:      "单个空格应被拒绝",
+			value:     " ",
+			wantValid: false,
+		},
+		{
+			name:      "空字符串应被拒绝",
+			value:     "",
+			wantValid: false,
+		},
+		{
+			name:      "制表符应被拒绝",
+			value:     "\t",
+			wantValid: false,
+		},
+		{
+			name:      "换行符应被拒绝",
+			value:     "\n",
+			wantValid: false,
+		},
+		{
+			name:      "混合空白字符应被拒绝",
+			value:     " \t\n ",
+			wantValid: false,
+		},
+		{
+			name:      "单个字符应通过",
+			value:     "a",
+			wantValid: true,
+		},
+	}
+
+	v, ok := binding.Validator.Engine().(*playgroundvalidator.Validate)
+	require.True(t, ok, "gin binding 校验器应为 *validator.Validate")
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			dto := struct {
+				Name string `binding:"notblank"`
+			}{Name: tc.value}
+
+			err := v.Struct(dto)
+			if tc.wantValid {
+				assert.NoError(t, err, "值 %q 应通过 notblank 校验", tc.value)
+			} else {
+				assert.Error(t, err, "值 %q 应被 notblank 拒绝", tc.value)
+			}
+		})
+	}
+}
+
+// TestNotBlank_DirectCall 直接调用 notBlank 函数验证非字符串类型直接通过
+func TestNotBlank_NonStringKind(t *testing.T) {
+	require.NoError(t, Setup())
+
+	// 非字符串类型（int）不受 notblank 约束，校验直接通过
+	type DTOInt struct {
+		Count int `binding:"notblank"`
+	}
+
+	v, ok := binding.Validator.Engine().(*playgroundvalidator.Validate)
+	require.True(t, ok)
+
+	dto := DTOInt{Count: 0}
+	err := v.Struct(dto)
+	assert.NoError(t, err, "非字符串字段应跳过 notblank 校验直接通过")
+}
+
+// TestOptionalURLClearingTag_ViaGinBinding 验证可清空 URL 字段的 PATCH 校验语义。
+func TestOptionalURLClearingTag_ViaGinBinding(t *testing.T) {
+	tests := []struct {
+		name      string
+		value     *string
+		wantValid bool
+	}{
+		{
+			name:      "未传字段应通过",
+			value:     nil,
+			wantValid: true,
+		},
+		{
+			name:      "空字符串应通过",
+			value:     ptrString(""),
+			wantValid: true,
+		},
+		{
+			name:      "纯空白应被拒绝",
+			value:     ptrString("   "),
+			wantValid: false,
+		},
+		{
+			name:      "合法 URL 应通过",
+			value:     ptrString("https://cdn.example.com/cover.webp"),
+			wantValid: true,
+		},
+		{
+			name:      "非法非空 URL 应拒绝",
+			value:     ptrString("not-a-url"),
+			wantValid: false,
+		},
+	}
+
+	v, ok := binding.Validator.Engine().(*playgroundvalidator.Validate)
+	require.True(t, ok)
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			dto := struct {
+				CoverURL *string `binding:"omitempty,url|eq=,max=500"`
+			}{CoverURL: tc.value}
+
+			err := v.Struct(dto)
+			if tc.wantValid {
+				assert.NoError(t, err)
+			} else {
+				assert.Error(t, err)
+			}
+		})
+	}
+}
+
+// TestJSONTagNameFunc 验证 Setup 将 JSON tag 用作字段名（影响校验错误中的 field 字段）
+func TestJSONTagNameFunc(t *testing.T) {
+	require.NoError(t, Setup())
+
+	type DTO struct {
+		UserName string `json:"user_name" binding:"required"`
+	}
+
+	v, ok := binding.Validator.Engine().(*playgroundvalidator.Validate)
+	require.True(t, ok)
+
+	err := v.Struct(DTO{})
+	require.Error(t, err)
+
+	var ve playgroundvalidator.ValidationErrors
+	require.ErrorAs(t, err, &ve)
+	require.Len(t, ve, 1)
+
+	// 字段名应使用 JSON tag 而非 struct 字段名
+	assert.Equal(t, "user_name", ve[0].Field(), "校验错误中的字段名应为 JSON tag 名")
+}
+
+func TestBindJSONStrictRejectsUnknownDuplicateAndTrailingValues(t *testing.T) {
+	require.NoError(t, Setup())
+
+	tests := []struct {
+		name    string
+		body    string
+		wantErr bool
+	}{
+		{name: "valid", body: `{"name":"one","nested":{"key":1}}`},
+		{name: "unknown", body: `{"name":"one","extra":true}`, wantErr: true},
+		{name: "duplicate", body: `{"name":"one","name":"two"}`, wantErr: true},
+		{name: "escaped duplicate", body: `{"name":"one","\u006eame":"two"}`, wantErr: true},
+		{name: "nested duplicate", body: `{"name":"one","nested":{"key":1,"key":2}}`, wantErr: true},
+		{name: "trailing value", body: `{"name":"one"} {"name":"two"}`, wantErr: true},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			context, _ := gin.CreateTestContext(httptest.NewRecorder())
+			context.Request = httptest.NewRequest("POST", "/", strings.NewReader(test.body))
+			var target struct {
+				Name   string `json:"name" binding:"required"`
+				Nested struct {
+					Key int `json:"key"`
+				} `json:"nested"`
+			}
+			err := BindJSONStrict(context, &target)
+			if test.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			require.Equal(t, "one", target.Name)
+			require.Equal(t, 1, target.Nested.Key)
+		})
+	}
+}
+
+func ptrString(value string) *string {
+	return &value
+}

package/dist/resources/templates/go-backend/internal/common/youtubeapi/client.go

@@ -0,0 +1,224 @@
+package youtubeapi
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"sync"
+	"time"
+
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/httpclient"
+	"{{module}}/internal/core/resilience"
+)
+
+const (
+	apiBaseURL            = "https://www.googleapis.com/youtube/v3"
+	circuitBreakerKey     = "youtube-data-api"
+	defaultRequestTimeout = 30 * time.Second
+	credentialTTL         = 5 * time.Minute
+)
+
+// Credential 是一次 YouTube Data API 调用所需的最小凭据快照。
+type Credential struct {
+	// ID 是 KOL 凭据记录标识。
+	ID int64
+	// APIKey 是解密后的 YouTube Data API 密钥。
+	APIKey string
+}
+
+// CredentialStore 管理 YouTube Data API 凭据选择和配额记账。
+type CredentialStore interface {
+	// GetAvailable 返回当前可用的 YouTube API 凭据。
+	GetAvailable(ctx context.Context) (*Credential, error)
+	// IncrementQuota 记录一次成功请求消耗的配额。
+	IncrementQuota(ctx context.Context, credentialID int64, cost int) error
+	// RecordFailure 记录供应商拒绝凭据的原因。
+	RecordFailure(ctx context.Context, credentialID int64, reason string) error
+}
+
+// Client 提供带凭据轮换、配额记账和熔断保护的 YouTube Data API 传输。
+type Client struct {
+	// httpClient 负责执行受超时和重试约束的 HTTP 请求。
+	httpClient *httpclient.Client
+	// credentialStore 负责凭据选择与配额记账。
+	credentialStore CredentialStore
+	// circuitBreaker 隔离 YouTube Data API 的连续故障。
+	circuitBreaker *resilience.CircuitBreakerService
+	// logger 记录不含密钥的传输诊断信息。
+	logger *zap.Logger
+
+	// mu 保护缓存凭据及其过期时间。
+	mu sync.RWMutex
+	// cachedCredential 减少每次请求读取并解密凭据的开销。
+	cachedCredential Credential
+	// credentialExpiresAt 限制缓存凭据的有效期。
+	credentialExpiresAt time.Time
+}
+
+// NewClient 创建 YouTube Data API 客户端。
+func NewClient(
+	logger *zap.Logger,
+	credentialStore CredentialStore,
+	circuitBreaker *resilience.CircuitBreakerService,
+) *Client {
+	client := httpclient.New(logger, httpclient.Options{
+		BaseURL:       apiBaseURL,
+		Timeout:       defaultRequestTimeout,
+		EnableLogging: false,
+		Retry: &httpclient.RetryConfig{
+			MaxRetries:            2,
+			RetryDelay:            2 * time.Second,
+			UseExponentialBackoff: true,
+			MaxDelay:              10 * time.Second,
+			RetryableStatusCodes: []int{
+				http.StatusInternalServerError,
+				http.StatusServiceUnavailable,
+				http.StatusGatewayTimeout,
+			},
+			RetryOnNetworkError: true,
+		},
+	})
+
+	circuitBreaker.ConfigureCircuit(circuitBreakerKey, resilience.CircuitBreakerConfig{
+		FailureThreshold:     10,
+		SuccessThreshold:     3,
+		ResetTimeout:         60 * time.Second,
+		RequestTimeout:       defaultRequestTimeout,
+		SlidingWindowSize:    20,
+		FailureRateThreshold: 60,
+		LogStateChanges:      true,
+	})
+
+	return &Client{
+		httpClient:      client,
+		credentialStore: credentialStore,
+		circuitBreaker:  circuitBreaker,
+		logger:          logger.Named("YouTubeDataAPIClient"),
+	}
+}
+
+// Get 执行 YouTube Data API GET 请求并记录配额消耗。
+func (c *Client) Get(
+	ctx context.Context,
+	pathAndQuery string,
+	// result 必须是具体 YouTube API 响应 DTO 的非空指针；传输层负责统一 JSON 解码。
+	result any,
+	quotaCost int,
+) error {
+	credential, err := c.getCredential(ctx)
+	if err != nil {
+		return fmt.Errorf("obtain YouTube API credential: %w", err)
+	}
+
+	requestURL, err := url.Parse(pathAndQuery)
+	if err != nil {
+		return fmt.Errorf("parse YouTube API request path: %w", err)
+	}
+	query := requestURL.Query()
+	query.Set("key", credential.APIKey)
+	requestURL.RawQuery = query.Encode()
+
+	// 熔断器以 any 统一承载不同外部传输结果，具体响应只在此闭包内校验状态。
+	_, err = c.circuitBreaker.Execute(ctx, circuitBreakerKey, func() (any, error) {
+		resp, requestErr := c.httpClient.Get(ctx, requestURL.String(), result)
+		if requestErr != nil {
+			return nil, requestErr
+		}
+		if resp.StatusCode == http.StatusForbidden {
+			return nil, c.handleForbidden(ctx, credential.ID, resp.Body)
+		}
+		if resp.StatusCode != http.StatusOK {
+			return nil, fmt.Errorf("YouTube API returned status %d", resp.StatusCode)
+		}
+		return resp, nil
+	})
+	if err != nil {
+		return err
+	}
+
+	if err := c.credentialStore.IncrementQuota(ctx, credential.ID, quotaCost); err != nil {
+		c.logger.Warn("failed to record YouTube API quota usage",
+			zap.Int64("credentialId", credential.ID),
+			zap.Int("cost", quotaCost),
+			zap.Error(err),
+		)
+	}
+	return nil
+}
+
+func (c *Client) getCredential(ctx context.Context) (*Credential, error) {
+	c.mu.RLock()
+	if c.cachedCredential.APIKey != "" && time.Now().Before(c.credentialExpiresAt) {
+		credential := c.cachedCredential
+		c.mu.RUnlock()
+		return &credential, nil
+	}
+	c.mu.RUnlock()
+
+	credential, err := c.credentialStore.GetAvailable(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if credential == nil || credential.ID <= 0 || credential.APIKey == "" {
+		return nil, fmt.Errorf("available YouTube API credential is invalid")
+	}
+
+	c.mu.Lock()
+	c.cachedCredential = *credential
+	c.credentialExpiresAt = time.Now().Add(credentialTTL)
+	c.mu.Unlock()
+	return credential, nil
+}
+
+func (c *Client) handleForbidden(ctx context.Context, credentialID int64, body []byte) error {
+	var response errorResponse
+	if err := json.Unmarshal(body, &response); err != nil {
+		c.invalidateCredential()
+		if recordErr := c.credentialStore.RecordFailure(ctx, credentialID, "forbidden"); recordErr != nil {
+			c.logger.Error("failed to record YouTube API credential failure",
+				zap.Int64("credentialId", credentialID),
+				zap.String("reason", "forbidden"),
+				zap.Error(recordErr),
+			)
+		}
+		return fmt.Errorf("YouTube API rejected credential %d", credentialID)
+	}
+
+	reason := "forbidden"
+	if len(response.Error.Errors) > 0 && response.Error.Errors[0].Reason != "" {
+		reason = response.Error.Errors[0].Reason
+	}
+	if reason != "rateLimitExceeded" {
+		c.invalidateCredential()
+		if err := c.credentialStore.RecordFailure(ctx, credentialID, reason); err != nil {
+			c.logger.Error("failed to record YouTube API credential failure",
+				zap.Int64("credentialId", credentialID),
+				zap.String("reason", reason),
+				zap.Error(err),
+			)
+		}
+	}
+	return fmt.Errorf("YouTube API request forbidden: %s", reason)
+}
+
+func (c *Client) invalidateCredential() {
+	c.mu.Lock()
+	c.cachedCredential = Credential{}
+	c.credentialExpiresAt = time.Time{}
+	c.mu.Unlock()
+}
+
+type errorResponse struct {
+	// Error 是 YouTube Data API 返回的错误容器。
+	Error struct {
+		// Errors 是供应商返回的具体错误列表。
+		Errors []struct {
+			// Reason 是 YouTube 定义的拒绝原因。
+			Reason string `json:"reason"`
+		} `json:"errors"`
+	} `json:"error"`
+}