Cadence技能函数(Skill Function)从入门到精通：核心用法与避坑指南

1次阅读

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

在 Cadence 工作流引擎中，Skill 函数（也称为本地活动）是一种特殊的函数执行方式。与 Activity 和 Child Workflow 相比，它最大的特点是 在 Worker 进程内同步执行，不需要通过任务队列分发。这种设计带来两个显著优势：执行延迟更低（通常在毫秒级），以及可以更灵活地访问工作流内部状态。

但这也意味着 Skill 函数必须遵循更严格的设计规范：执行时间不应超过几秒钟，且需要自行处理并发安全和幂等问题。理解这些特性差异，是正确使用 Skill 函数的前提。

规范的 Skill 函数签名应包含以下要素：

// 标准签名示例
func ProcessOrder(ctx context.Context, params OrderParams) (OrderResult, error) {// 实现逻辑}

上下文参数：首参数必须为context.Context，用于超时控制和取消信号传递
输入参数：建议使用结构体封装，避免参数膨胀
返回值：必须返回 error 类型，非错误结果通过单独返回值传递

Cadence 提供分级重试策略配置：

retryPolicy := &cadence.RetryPolicy{
    InitialInterval:    time.Second,
    BackoffCoefficient: 2.0,
    MaximumInterval:    time.Minute,
    ExpirationInterval: time.Hour * 24,
    NonRetriableErrorReasons: []string{"INVALID_ARGUMENT"}, // 特定错误不重试
}

关键设计要点：

瞬态错误（如网络抖动）应自动重试
业务逻辑错误应通过自定义错误类型明确标识
不可恢复错误应立即终止执行

使用 sync.Mutex 保证共享资源访问安全：

var processingOrders sync.Map // 线程安全的订单处理状态记录

func SafeOrderUpdate(ctx context.Context, orderID string) error {
    // 获取订单专属锁
    mutex, _ := processingOrders.LoadOrStore(orderID, &sync.Mutex{})
    lock := mutex.(*sync.Mutex)
    lock.Lock()
    defer lock.Unlock()

    // 临界区操作
    return nil
}

// 带超时控制的幂等处理
func ProcessPayment(ctx context.Context, req PaymentRequest) (PaymentReceipt, error) {
    // 设置函数级超时（必须小于工作流超时）ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()

    // 幂等键检查（使用业务 ID+ 操作类型）idempotencyKey := fmt.Sprintf("pay_%s", req.TransactionID)
    if err := checkIdempotency(idempotencyKey); err != nil {return PaymentReceipt{}, fmt.Errorf("idempotency check failed: %w", err)
    }

    // 实际支付逻辑
    receipt, err := paymentGateway.Charge(ctx, req.Amount, req.Currency)
    if err != nil {return PaymentReceipt{}, categorizePaymentError(err)
    }

    // 记录幂等状态（需持久化存储）if err := storeIdempotency(idempotencyKey, receipt); err != nil {log.Warn("idempotency state save failed", zap.Error(err))
    }

    return receipt, nil
}

日志规范：
每个 Skill 函数入口 / 出口记录耗时
错误日志包含完整上下文（请求 ID、参数快照等）
使用结构化日志字段

// 典型日志记录
log.Info("skill_function_start",
    zap.String("func", "ProcessPayment"),
    zap.Duration("timeout", remainingTimeout(ctx)),
    zap.Any("request", sanitizeRequest(req)))