---

name: temporal-golang-pro description: "用于使用 Temporal Go SDK 构建持久化分布式系统。涵盖确定性工作流规则、mTLS Worker 配置和高级模式。" risk: safe source: self date_added: "2026-02-27"

Temporal Go SDK (temporal-golang-pro)

概述

使用 Temporal Go SDK 构建弹性、可扩展且确定性的分布式系统的专家级指南。此技能将模糊的编排需求转化为生产级 Go 实现，专注于持久化执行、严格确定性和企业级 Worker 配置。

何时使用此技能

• 设计分布式系统：当构建需要持久化状态和可靠编排的微服务时。
• 实现复杂工作流：使用 Go SDK 处理长时间运行的流程（数天/数月）或复杂的 Saga 模式。
• 优化性能：当 Worker 需要精细调优的并发、mTLS 安全或自定义拦截器时。
• 确保可靠性：实现幂等 Activity、优雅的错误处理和复杂的重试策略。
• 维护与演进：对运行中的工作流进行版本控制或执行零停机 Worker 更新。

不要在以下情况使用此技能

• 使用其他 SDK（Python、Java、TypeScript）的 Temporal — 请参考它们各自的 -pro 技能。
• 任务是简单的请求/响应，不需要持久化或协调。
• 没有实现的高层设计（使用 workflow-orchestration-patterns）。

分步指南

1. 收集上下文：主动询问：
   • 目标 Temporal 集群（Cloud vs. 自托管）和 Namespace。
   • Task Queue 名称和预期吞吐量。
   • 安全需求（mTLS 路径，认证）。
   • 故障模式和期望的重试/超时策略。
2. 验证确定性：在建议工作流代码之前，根据以下 5 条规则 验证：
   • 不使用原生 Go 并发（goroutine）。
   • 不使用原生时间（time.Now、time.Sleep）。
   • 不使用非确定性 map 迭代（必须排序 key）。
   • 不直接进行外部 I/O 或网络调用。
   • 不使用非确定性随机数。
3. 增量实现：从共享的 Protobuf/数据类开始，然后是 Activity，接着是 Workflow，最后是 Worker。
4. 利用资源：如果实现需要高级模式（Saga、拦截器、Replay 测试），明确参考实现手册和测试策略。

能力

Go SDK 实现

• Worker 管理：深入了解 worker.Options，包括 MaxConcurrentActivityTaskPollers、WorkerStopTimeout 和 StickyScheduleToStartTimeout。
• 拦截器：实现 Client、Worker 和 Workflow 拦截器用于横切关注点（日志、追踪、认证）。
• 自定义数据转换器：集成 Protobuf、加密负载或自定义 JSON 序列化。

高级工作流模式

• 持久化并发：使用 workflow.Go、workflow.Channel 和 workflow.Selector 替代原生原语。
• 版本控制：使用 workflow.GetVersion 和 workflow.GetReplaySafeLogger 实现安全的代码演进。
• 大规模处理：使用 ContinueAsNew 管理历史大小限制的模式（默认：50MB 或 50K 事件）。
• 子工作流：管理生命周期、取消和父子信号传播。

测试与可观测性

• 测试套件精通：使用 WorkflowTestSuite 进行单元和功能测试，支持确定性时间控制。
• Mock：复杂的 Activity 和子工作流 Mock 策略。
• Replay 测试：根据生产事件历史验证代码变更。
• 指标：配置 Prometheus/OpenTelemetry 导出器用于 Worker 性能追踪。

示例

示例 1：版本化工作流（确定性）

// Note: imports omitted. Requires 'go.temporal.io/sdk/workflow', 'go.temporal.io/sdk/temporal', and 'time'.
func SubscriptionWorkflow(ctx workflow.Context, userID string) error {
    // 1. Versioning for logic evolution (v1 = DefaultVersion)
    v := workflow.GetVersion(ctx, "billing_logic", workflow.DefaultVersion, 2)

    for i := 0; i < 12; i++ {
        ao := workflow.ActivityOptions{
            StartToCloseTimeout: 5 * time.Minute,
            RetryPolicy: &temporal.RetryPolicy{MaximumAttempts: 3},
        }
        ctx = workflow.WithActivityOptions(ctx, ao)

        // 2. Activity Execution (Always handle errors)
        err := workflow.ExecuteActivity(ctx, ChargePaymentActivity, userID).Get(ctx, nil)
        if err != nil {
            workflow.GetLogger(ctx).Error("Payment failed", "Error", err)
            return err
        }

        // 3. Durable Sleep (Time-skipping safe)
        sleepDuration := 30 * 24 * time.Hour
        if v >= 2 {
            sleepDuration = 28 * 24 * time.Hour
        }

        if err := workflow.Sleep(ctx, sleepDuration); err != nil {
            return err
        }
    }
    return nil
}