
关于
使用 Temporal Go SDK 构建持久化分布式系统。涵盖确定性工作流规则、mTLS Worker 配置和高级模式
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)。
分步指南
- 收集上下文:主动询问:
- 目标 Temporal 集群(Cloud vs. 自托管)和 Namespace。
- Task Queue 名称和预期吞吐量。
- 安全需求(mTLS 路径,认证)。
- 故障模式和期望的重试/超时策略。
- 验证确定性:在建议工作流代码之前,根据以下 5 条规则 验证:
- 不使用原生 Go 并发(goroutine)。
- 不使用原生时间(
time.Now、time.Sleep)。 - 不使用非确定性 map 迭代(必须排序 key)。
- 不直接进行外部 I/O 或网络调用。
- 不使用非确定性随机数。
- 增量实现:从共享的 Protobuf/数据类开始,然后是 Activity,接着是 Workflow,最后是 Worker。
- 利用资源:如果实现需要高级模式(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
}
兼容工具
Claude CodeCursor
标签
后端开发
