Cadence Skill 下载 CVN 实战指南：从零搭建到生产环境避坑

1次阅读

没有评论

共计 4073 个字符，预计需要花费 11 分钟才能阅读完成。

在微服务架构下实现文件下载功能时，开发者常常面临几个核心挑战：

身份认证：如何确保下载请求来自合法用户，同时避免认证信息泄露
断点续传：大文件下载过程中网络中断后如何恢复，避免重复传输
并发控制：防止同一文件被重复下载导致资源浪费
错误处理：网络波动、服务重启等场景下的可靠性和一致性保证

传统 HTTP 下载方案虽然简单直接，但在处理这些问题时往往需要自行实现大量边缘逻辑，增加了系统复杂度和维护成本。

优点：实现简单，无需额外基础设施
缺点：
需要自行处理断点续传（Range 头）
服务重启后无法恢复下载状态
难以保证幂等性

优点：
内置状态管理，自动保存进度
天然支持幂等操作
自带重试和超时机制
可观测性强（通过 Cadence UI）
缺点：
需要部署和维护 Cadence 集群
学习曲线略陡

type DownloadCVNWorkflow struct {cadence.Workflow}

func (w *DownloadCVNWorkflow) Execute(ctx cadence.Context, fileID string) error {
    options := cadence.ActivityOptions{
        ScheduleToStartTimeout: time.Minute,
        StartToCloseTimeout:    time.Hour,
        HeartbeatTimeout:       time.Second * 30,
        RetryPolicy: &cadence.RetryPolicy{
            InitialInterval:    time.Second,
            BackoffCoefficient: 2.0,
            MaximumInterval:    time.Minute,
            MaximumAttempts:    3,
        },
    }
    ctx = cadence.WithActivityOptions(ctx, options)

    // 步骤 1：获取下载 URL
    var downloadURL string
    err := cadence.ExecuteActivity(ctx, GetDownloadURLAcitivity, fileID).Get(ctx, &downloadURL)
    if err != nil {return fmt.Errorf("failed to get download URL: %w", err)
    }

    // 步骤 2：下载并校验文件
    var localPath string
    err = cadence.ExecuteActivity(ctx, DownloadAndVerifyActivity, downloadURL).Get(ctx, &localPath)
    if err != nil {return fmt.Errorf("failed to download file: %w", err)
    }

    return nil
}

func DownloadAndVerifyActivity(ctx context.Context, downloadURL string) (string, error) {
    // 创建临时文件
    tmpFile, err := ioutil.TempFile("","cvn_download_")
    if err != nil {return "", fmt.Errorf("failed to create temp file: %w", err)
    }
    defer os.Remove(tmpFile.Name())

    // 执行下载
    resp, err := http.Get(downloadURL)
    if err != nil {return "", fmt.Errorf("HTTP request failed: %w", err)
    }
    defer resp.Body.Close()

    // 校验 Content-Type
    if !strings.Contains(resp.Header.Get("Content-Type"), "application/cvn") {return "", errors.New("invalid content type")
    }

    // 计算文件哈希
    hasher := sha256.New()
    tee := io.TeeReader(resp.Body, hasher)

    if _, err := io.Copy(tmpFile, tee); err != nil {return "", fmt.Errorf("failed to write file: %w", err)
    }

    // 验证文件大小
    fileInfo, err := tmpFile.Stat()
    if err != nil {return "", fmt.Errorf("failed to get file info: %w", err)
    }

    if fileInfo.Size() == 0 {return "", errors.New("empty file")
    }

    // 在这里可以添加更多业务校验逻辑

    // 移动临时文件到正式位置
    finalPath := filepath.Join("/cvn_storage", filepath.Base(downloadURL))
    if err := os.Rename(tmpFile.Name(), finalPath); err != nil {return "", fmt.Errorf("failed to move file: %w", err)
    }

    return finalPath, nil
}

Cadence 提供了灵活的重试配置：

InitialInterval: 初始重试间隔
BackoffCoefficient: 退避系数
MaximumInterval: 最大重试间隔
MaximumAttempts: 最大尝试次数

对于下载场景，建议设置：

较短的心跳超时（如 30 秒）以便快速检测失败
较长的总超时（如 1 小时）以容纳大文件下载
适中的重试次数（3- 5 次）

func acquireDownloadLock(ctx cadence.Context, fileID string) (func(), error) {lockKey := fmt.Sprintf("download_lock_%s", fileID)

    // 尝试获取锁
    if err := cadence.SideEffect(ctx, func() (interface{}, error) {return distributedLock.Acquire(lockKey, 10*time.Minute)
    }).Get(&struct{}{}); err != nil {return nil, fmt.Errorf("failed to acquire lock: %w", err)
    }

    // 返回释放锁的函数
    releaseFn := func() {_ = cadence.SideEffect(ctx, func() (interface{}, error) {return nil, distributedLock.Release(lockKey)
        })
    }

    return releaseFn, nil
}

关键指标建议：

下载成功率
平均下载耗时
文件大小分布
重试次数统计

可以通过 Cadence 的 cadence.WithActivityOptions 配置上下文，在 Activity 中记录：

// 在 Activity 开始时
metrics.Increment("download_attempts")
startTime := time.Now()

defer func() {duration := time.Since(startTime)
    metrics.Record("download_duration_ms", duration.Milliseconds())
    if err != nil {metrics.Increment("download_failures")
    }
}()

未处理 SIGTERM 导致工作流中断

解决方案：在工作流中注册信号处理器，优雅停止下载

go func() {sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGTERM)
    <-sigChan
    // 保存当前下载状态
    cadence.RecordHeartbeat(ctx, currentProgress)
    os.Exit(0)
}()

未校验文件完整性导致数据损坏

解决方案：下载完成后必须验证文件哈希

expectedHash := "..." // 从元数据获取
actualHash := hex.EncodeToString(hasher.Sum(nil))
if actualHash != expectedHash {return "", fmt.Errorf("hash mismatch: expected %s, got %s", expectedHash, actualHash)
}

临时文件未清理导致磁盘爆满
解决方案：使用 defer 确保清理，并设置定期扫描任务

可以考虑以下方案：

在 Activity 中使用带宽限制器

rateLimiter := rate.NewLimiter(rate.Limit(1024*1024), 1024*1024) // 1MB/s
reader := &rateLimitedReader{
    reader:  resp.Body,
    limiter: rateLimiter,
}
io.Copy(tmpFile, reader)