@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/storage/oss_provider.go

@@ -0,0 +1,398 @@
+package storage
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	aliyunoss "github.com/aliyun/aliyun-oss-go-sdk/oss"
+	"go.uber.org/zap"
+)
+
+// OSSConfig 阿里云 OSS Provider 配置。
+type OSSConfig struct {
+	// 阿里云 OSS 区域。
+	Region string
+	// 阿里云 OSS Endpoint。
+	Endpoint string
+	// 访问密钥 ID。
+	AccessKeyID string
+	// 访问密钥 Secret。
+	SecretAccessKey string
+}
+
+// OSSProvider 基于阿里云官方 OSS SDK 的存储实现。
+type OSSProvider struct {
+	client *aliyunoss.Client
+	logger *zap.Logger
+}
+
+// NewOSSProvider 创建阿里云 OSS Provider 实例。
+func NewOSSProvider(cfg OSSConfig, logger *zap.Logger) (*OSSProvider, error) {
+	if strings.TrimSpace(cfg.Region) == "" {
+		return nil, fmt.Errorf("oss region is required")
+	}
+	endpoint := strings.TrimSpace(cfg.Endpoint)
+	if endpoint == "" {
+		endpoint = defaultOSSEndpoint(cfg.Region)
+	}
+	if strings.TrimSpace(cfg.AccessKeyID) == "" || strings.TrimSpace(cfg.SecretAccessKey) == "" {
+		return nil, fmt.Errorf("oss credentials are required")
+	}
+
+	client, err := aliyunoss.New(
+		endpoint,
+		cfg.AccessKeyID,
+		cfg.SecretAccessKey,
+		aliyunoss.Region(cfg.Region),
+		aliyunoss.AuthVersion(aliyunoss.AuthV4),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("create oss client: %w", err)
+	}
+
+	return &OSSProvider{
+		client: client,
+		logger: logger.Named("OSSProvider"),
+	}, nil
+}
+
+// GeneratePresignedUploadURL 生成预签名上传 URL。
+func (p *OSSProvider) GeneratePresignedUploadURL(ctx context.Context, params PresignUploadParams) (*PresignUploadResult, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, err
+	}
+	expiresIn := normalizePresignExpiry(params.ExpiresIn)
+	options := ossOptions(ctx, params.ContentType, params.Metadata)
+
+	signedURL, err := bucket.SignURL(params.Key, aliyunoss.HTTPPut, int64(expiresIn.Seconds()), options...)
+	if err != nil {
+		p.logger.Error("oss presigned upload url generation failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("generate oss presigned upload url: %w", err)
+	}
+
+	headers := make(map[string]string)
+	if strings.TrimSpace(params.ContentType) != "" {
+		headers["Content-Type"] = strings.TrimSpace(params.ContentType)
+	}
+
+	return &PresignUploadResult{
+		URL:       signedURL,
+		Headers:   headers,
+		ExpiresAt: time.Now().UTC().Add(expiresIn),
+	}, nil
+}
+
+// GeneratePresignedDownloadURL 生成预签名下载 URL。
+func (p *OSSProvider) GeneratePresignedDownloadURL(ctx context.Context, params PresignDownloadParams) (*PresignDownloadResult, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, err
+	}
+	expiresIn := normalizePresignExpiry(params.ExpiresIn)
+	options := []aliyunoss.Option{aliyunoss.WithContext(ctx)}
+	if strings.TrimSpace(params.DownloadFilename) != "" {
+		options = append(options, aliyunoss.ResponseContentDisposition(downloadContentDisposition(params.DownloadFilename)))
+	}
+
+	signedURL, err := bucket.SignURL(params.Key, aliyunoss.HTTPGet, int64(expiresIn.Seconds()), options...)
+	if err != nil {
+		p.logger.Error("oss presigned download url generation failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("generate oss presigned download url: %w", err)
+	}
+
+	return &PresignDownloadResult{
+		URL:       signedURL,
+		ExpiresAt: time.Now().UTC().Add(expiresIn),
+	}, nil
+}
+
+// Upload 服务端直接上传对象。
+func (p *OSSProvider) Upload(ctx context.Context, params UploadParams) (*UploadResult, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, err
+	}
+	options := ossOptions(ctx, params.ContentType, params.Metadata)
+	if params.Size > 0 {
+		options = append(options, aliyunoss.ContentLength(params.Size))
+	}
+
+	if err := bucket.PutObject(params.Key, params.Body, options...); err != nil {
+		p.logger.Error("oss upload failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("upload oss object: %w", err)
+	}
+
+	return &UploadResult{
+		Location: ossLocation(params.Bucket, params.Key),
+	}, nil
+}
+
+// UploadIfAbsent 通过 OSS 禁止覆盖条件原子创建不可变对象。
+func (p *OSSProvider) UploadIfAbsent(
+	ctx context.Context,
+	params UploadParams,
+) (*UploadResult, bool, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, false, err
+	}
+	options := append(ossOptions(ctx, params.ContentType, params.Metadata), aliyunoss.ForbidOverWrite(true))
+	if params.Size > 0 {
+		options = append(options, aliyunoss.ContentLength(params.Size))
+	}
+	if err := bucket.PutObject(params.Key, params.Body, options...); err != nil {
+		var serviceErr aliyunoss.ServiceError
+		if errors.As(err, &serviceErr) && (serviceErr.StatusCode == http.StatusConflict || serviceErr.StatusCode == http.StatusPreconditionFailed) {
+			return nil, false, nil
+		}
+		return nil, false, fmt.Errorf("create immutable oss object: %w", err)
+	}
+	return &UploadResult{Location: ossLocation(params.Bucket, params.Key)}, true, nil
+}
+
+// Delete 删除对象。
+func (p *OSSProvider) Delete(ctx context.Context, params DeleteParams) error {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return err
+	}
+	if err := bucket.DeleteObject(params.Key, aliyunoss.WithContext(ctx)); err != nil {
+		p.logger.Error("oss delete failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return fmt.Errorf("delete oss object: %w", err)
+	}
+	return nil
+}
+
+var _ ImmutableObjectProvider = (*OSSProvider)(nil)
+
+// HeadObject 获取对象元数据。
+func (p *OSSProvider) HeadObject(ctx context.Context, params HeadObjectParams) (*ObjectMetadata, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, err
+	}
+	header, err := bucket.GetObjectDetailedMeta(params.Key, aliyunoss.WithContext(ctx))
+	if err != nil {
+		p.logger.Error("oss head object failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("head oss object: %w", err)
+	}
+
+	contentLength, _ := strconv.ParseInt(header.Get("Content-Length"), 10, 64)
+	lastModified, _ := http.ParseTime(header.Get("Last-Modified"))
+
+	return &ObjectMetadata{
+		ContentType:   header.Get("Content-Type"),
+		ContentLength: contentLength,
+		ETag:          header.Get("ETag"),
+		LastModified:  lastModified,
+		Metadata:      ossUserMetadata(header),
+	}, nil
+}
+
+// InitiateMultipartUpload 发起分片上传。
+func (p *OSSProvider) InitiateMultipartUpload(ctx context.Context, params InitiateMultipartParams) (*InitiateMultipartResult, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, err
+	}
+	result, err := bucket.InitiateMultipartUpload(params.Key, ossOptions(ctx, params.ContentType, params.Metadata)...)
+	if err != nil {
+		p.logger.Error("oss initiate multipart upload failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("initiate oss multipart upload: %w", err)
+	}
+	return &InitiateMultipartResult{UploadID: result.UploadID}, nil
+}
+
+// GeneratePartPresignedURL 生成分片预签名上传 URL。
+func (p *OSSProvider) GeneratePartPresignedURL(ctx context.Context, params PresignPartParams) (*PresignPartResult, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, err
+	}
+	expiresIn := normalizePresignExpiry(params.ExpiresIn)
+	options := []aliyunoss.Option{
+		aliyunoss.WithContext(ctx),
+		aliyunoss.AddParam("partNumber", strconv.FormatInt(int64(params.PartNumber), 10)),
+		aliyunoss.AddParam("uploadId", params.UploadID),
+	}
+
+	signedURL, err := bucket.SignURL(params.Key, aliyunoss.HTTPPut, int64(expiresIn.Seconds()), options...)
+	if err != nil {
+		p.logger.Error("oss presigned part url generation failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.String("uploadId", params.UploadID),
+			zap.Int32("partNumber", params.PartNumber),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("generate oss part presigned url: %w", err)
+	}
+
+	return &PresignPartResult{
+		URL:       signedURL,
+		ExpiresAt: time.Now().UTC().Add(expiresIn),
+	}, nil
+}
+
+// CompleteMultipartUpload 完成分片上传。
+func (p *OSSProvider) CompleteMultipartUpload(ctx context.Context, params CompleteMultipartParams) (*CompleteMultipartResult, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, err
+	}
+	upload := aliyunoss.InitiateMultipartUploadResult{
+		Bucket:   params.Bucket,
+		Key:      params.Key,
+		UploadID: params.UploadID,
+	}
+	parts := make([]aliyunoss.UploadPart, len(params.Parts))
+	for i := range params.Parts {
+		parts[i] = aliyunoss.UploadPart{
+			PartNumber: int(params.Parts[i].PartNumber),
+			ETag:       params.Parts[i].ETag,
+		}
+	}
+
+	result, err := bucket.CompleteMultipartUpload(upload, parts, aliyunoss.WithContext(ctx))
+	if err != nil {
+		p.logger.Error("oss complete multipart upload failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.String("uploadId", params.UploadID),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("complete oss multipart upload: %w", err)
+	}
+
+	return &CompleteMultipartResult{
+		ETag:     result.ETag,
+		Location: result.Location,
+	}, nil
+}
+
+// AbortMultipartUpload 取消分片上传。
+func (p *OSSProvider) AbortMultipartUpload(ctx context.Context, params AbortMultipartParams) error {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return err
+	}
+	upload := aliyunoss.InitiateMultipartUploadResult{
+		Bucket:   params.Bucket,
+		Key:      params.Key,
+		UploadID: params.UploadID,
+	}
+	if err := bucket.AbortMultipartUpload(upload, aliyunoss.WithContext(ctx)); err != nil {
+		p.logger.Error("oss abort multipart upload failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.String("uploadId", params.UploadID),
+			zap.Error(err),
+		)
+		return fmt.Errorf("abort oss multipart upload: %w", err)
+	}
+	return nil
+}
+
+// Download 服务端直接下载对象内容。
+func (p *OSSProvider) Download(ctx context.Context, params DownloadParams) (*DownloadResult, error) {
+	bucket, err := p.bucket(params.Bucket)
+	if err != nil {
+		return nil, err
+	}
+	body, err := bucket.GetObject(params.Key, aliyunoss.WithContext(ctx))
+	if err != nil {
+		p.logger.Error("oss download failed",
+			zap.String("bucket", params.Bucket),
+			zap.String("key", params.Key),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("download oss object: %w", err)
+	}
+	return &DownloadResult{Body: body}, nil
+}
+
+func (p *OSSProvider) bucket(bucketName string) (*aliyunoss.Bucket, error) {
+	name := strings.TrimSpace(bucketName)
+	if name == "" {
+		return nil, fmt.Errorf("oss bucket is required")
+	}
+	bucket, err := p.client.Bucket(name)
+	if err != nil {
+		return nil, fmt.Errorf("create oss bucket handle: %w", err)
+	}
+	return bucket, nil
+}
+
+func normalizePresignExpiry(expiresIn time.Duration) time.Duration {
+	if expiresIn <= 0 {
+		return 15 * time.Minute
+	}
+	if expiresIn < time.Second {
+		return time.Second
+	}
+	return expiresIn
+}
+
+func ossOptions(ctx context.Context, contentType string, metadata map[string]string) []aliyunoss.Option {
+	options := []aliyunoss.Option{aliyunoss.WithContext(ctx)}
+	if strings.TrimSpace(contentType) != "" {
+		options = append(options, aliyunoss.ContentType(strings.TrimSpace(contentType)))
+	}
+	for key, value := range metadata {
+		if strings.TrimSpace(key) != "" {
+			options = append(options, aliyunoss.Meta(strings.TrimSpace(key), value))
+		}
+	}
+	return options
+}
+
+func ossUserMetadata(header http.Header) map[string]string {
+	metadata := make(map[string]string)
+	for key, values := range header {
+		if !strings.HasPrefix(strings.ToLower(key), "X-Oss-Meta-") || len(values) == 0 {
+			continue
+		}
+		metadata[strings.TrimPrefix(key, "X-Oss-Meta-")] = values[0]
+	}
+	return metadata
+}
+
+func ossLocation(bucketName string, key string) string {
+	return fmt.Sprintf("oss://%s/%s", bucketName, key)
+}
+
+func defaultOSSEndpoint(region string) string {
+	return fmt.Sprintf("https://oss-%s.aliyuncs.com", strings.TrimSpace(region))
+}
+
+var _ Provider = (*OSSProvider)(nil)

package/dist/resources/templates/go-backend/internal/core/storage/oss_provider_test.go

@@ -0,0 +1,89 @@
+package storage
+
+import (
+	"context"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+func TestOSSProviderGeneratesAliyunSignedDownloadURL(t *testing.T) {
+	provider, err := NewOSSProvider(OSSConfig{
+		Region:          "cn-hangzhou",
+		Endpoint:        "https://oss-cn-hangzhou.aliyuncs.com",
+		AccessKeyID:     "test-access-key",
+		SecretAccessKey: "test-secret-key",
+	}, zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewOSSProvider() error = %v", err)
+	}
+
+	result, err := provider.GeneratePresignedDownloadURL(context.Background(), PresignDownloadParams{
+		Bucket:    "onex-product-assets-prod",
+		Key:       "catalog/catalog/products/p01/main.webp",
+		ExpiresIn: 10 * time.Minute,
+	})
+	if err != nil {
+		t.Fatalf("GeneratePresignedDownloadURL() error = %v", err)
+	}
+	if result == nil || strings.TrimSpace(result.URL) == "" {
+		t.Fatal("GeneratePresignedDownloadURL() returned empty URL")
+	}
+	parsed, err := url.Parse(result.URL)
+	if err != nil {
+		t.Fatalf("signed URL parse error = %v", err)
+	}
+	if parsed.Host != "onex-product-assets-prod.oss-cn-hangzhou.aliyuncs.com" {
+		t.Fatalf("signed URL host = %q", parsed.Host)
+	}
+	if strings.Contains(result.URL, "X-Amz-") {
+		t.Fatalf("signed URL uses AWS SigV4 params: %s", result.URL)
+	}
+	query := parsed.Query()
+	if query.Get("x-oss-signature-version") != "OSS4-HMAC-SHA256" {
+		t.Fatalf("x-oss-signature-version = %q", query.Get("x-oss-signature-version"))
+	}
+	if query.Get("x-oss-signature") == "" {
+		t.Fatal("x-oss-signature is empty")
+	}
+}
+
+func TestOSSProviderGeneratesAliyunSignedPartURL(t *testing.T) {
+	provider, err := NewOSSProvider(OSSConfig{
+		Region:          "cn-hangzhou",
+		Endpoint:        "https://oss-cn-hangzhou.aliyuncs.com",
+		AccessKeyID:     "test-access-key",
+		SecretAccessKey: "test-secret-key",
+	}, zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewOSSProvider() error = %v", err)
+	}
+
+	result, err := provider.GeneratePartPresignedURL(context.Background(), PresignPartParams{
+		Bucket:     "onex-product-assets-prod",
+		Key:        "catalog/catalog/products/p01/main.webp",
+		UploadID:   "upload-id-001",
+		PartNumber: 3,
+		ExpiresIn:  10 * time.Minute,
+	})
+	if err != nil {
+		t.Fatalf("GeneratePartPresignedURL() error = %v", err)
+	}
+	parsed, err := url.Parse(result.URL)
+	if err != nil {
+		t.Fatalf("signed URL parse error = %v", err)
+	}
+	query := parsed.Query()
+	if query.Get("partNumber") != "3" {
+		t.Fatalf("partNumber = %q", query.Get("partNumber"))
+	}
+	if query.Get("uploadId") != "upload-id-001" {
+		t.Fatalf("uploadId = %q", query.Get("uploadId"))
+	}
+	if query.Get("x-oss-signature") == "" {
+		t.Fatal("x-oss-signature is empty")
+	}
+}

package/dist/resources/templates/go-backend/internal/core/storage/path.go

@@ -0,0 +1,110 @@
+package storage
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// ===============================================================
+// 路径生成策略
+// ===============================================================
+
+// PathStrategy 对象键路径生成策略
+type PathStrategy struct {
+	// 产品代码（用于 shared 模式下的路径前缀）
+	ProductCode string
+	// 存储桶策略："shared" 表示多产品共享桶，"dedicated" 表示产品独占桶
+	BucketStrategy string
+}
+
+// ObjectKeyInput 对象键生成输入
+type ObjectKeyInput struct {
+	// 业务治理前缀，由调用层策略决定；PathStrategy 只做格式化
+	Prefix string
+	// 文件分类（image/video/audio/document 等）
+	Category string
+	// 原始文件名
+	Filename string
+}
+
+// GenerateObjectKey 生成对象存储键
+//
+// shared 模式: {product}/{prefix}/{category}/{YYYY/MM/DD}/{random_hex}/{safe_filename}
+// dedicated 模式: {prefix}/{category}/{YYYY/MM/DD}/{random_hex}/{safe_filename}
+func (s *PathStrategy) GenerateObjectKey(input ObjectKeyInput) (string, error) {
+	category, err := normalizeObjectKeySegment(input.Category, "category")
+	if err != nil {
+		return "", err
+	}
+	prefix, err := normalizeObjectKeyPrefix(input.Prefix)
+	if err != nil {
+		return "", err
+	}
+	safeFilename := SanitizeFilename(input.Filename)
+	datePath := time.Now().UTC().Format("2006/01/02")
+	randomHex, err := generateRandomHex(8)
+	if err != nil {
+		return "", err
+	}
+
+	segments := make([]string, 0, 8)
+	if s.BucketStrategy == "shared" {
+		productCode, err := normalizeObjectKeySegment(s.ProductCode, "product_code")
+		if err != nil {
+			return "", err
+		}
+		segments = append(segments, productCode)
+	}
+	if prefix != "" {
+		segments = append(segments, strings.Split(prefix, "/")...)
+	}
+	segments = append(segments, category, datePath, randomHex, safeFilename)
+	return strings.Join(segments, "/"), nil
+}
+
+// generateRandomHex 生成指定字节数的十六进制字符串
+func generateRandomHex(nBytes int) (string, error) {
+	b := make([]byte, nBytes)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("crypto/rand.Read failed: %w", err)
+	}
+	return hex.EncodeToString(b), nil
+}
+
+func normalizeObjectKeyPrefix(prefix string) (string, error) {
+	value := strings.Trim(strings.TrimSpace(prefix), "/")
+	if value == "" {
+		return "", nil
+	}
+	parts := strings.Split(value, "/")
+	normalized := make([]string, 0, len(parts))
+	for _, part := range parts {
+		segment, err := normalizeObjectKeySegment(part, "prefix")
+		if err != nil {
+			return "", err
+		}
+		normalized = append(normalized, segment)
+	}
+	return strings.Join(normalized, "/"), nil
+}
+
+func normalizeObjectKeySegment(segment string, field string) (string, error) {
+	value := strings.TrimSpace(segment)
+	if value == "" {
+		return "", fmt.Errorf("%s is required", field)
+	}
+	if value == "." || value == ".." {
+		return "", fmt.Errorf("%s contains invalid path segment", field)
+	}
+	if strings.Contains(value, "\\") {
+		return "", fmt.Errorf("%s contains invalid path separator", field)
+	}
+	sanitized := SanitizeFilename(value)
+	if sanitized != value || sanitized == "unnamed" {
+		return "", fmt.Errorf("%s contains unsafe characters", field)
+	}
+	return value, nil
+}