name: temporal-golang-prodescription: “Use when building durable distributed systems with Temporal Go SDK. Covers deterministic workflow rules, mTLS worker configs, and advanced patterns.”risk: safesource: selfdate_added: “2026-02-27”Temporal Go SDK (temporal-golang-pro)概述使用 Temporal Go SDK 构建弹性、可扩展且确定性的分布式系统的专家级指南。本技能将模糊的编排需求转化为生产级的 Go 实现专注于持久执行、严格的确定性以及企业级工作器配置。何时使用此技能设计分布式系统: 当构建需要持久状态和可靠编排的微服务时。实现复杂工作流: 使用 Go SDK 处理长时间运行的流程数天/数月或复杂的 Saga 模式。优化性能: 当工作器需要精细调优的并发、mTLS 安全性或自定义拦截器时。确保可靠性: 实现幂等活动、优雅的错误处理和复杂的重试策略。维护与演进: 对运行中的工作流进行版本管理或执行零停机工作器更新。不要在此情况下使用此技能将 Temporal 与其他 SDKPython、Java、TypeScript一起使用——请参考各自的-pro技能。任务是没有持久性或协调需求的简单请求/响应。只有高层设计而无实现请使用workflow-orchestration-patterns。分步指南收集上下文: 主动询问目标Temporal 集群云端 vs. 自托管和命名空间。任务队列名称和预期吞吐量。安全要求mTLS 路径、身份验证。故障模式和期望的重试/超时策略。验证确定性: 在建议工作流代码之前根据以下5 条规则进行验证不使用原生 Go 并发goroutine。不使用原生时间time.Now、time.Sleep。不确定的 map 迭代必须对键排序。不直接进行外部 I/O 或网络调用。不使用不确定的随机数。增量实现: 从共享的 Protobuf/数据类开始然后是活动接着是工作流最后是工作器。利用资源: 如果实现需要高级模式Saga、拦截器、重放测试请明确参考实施手册和测试策略。能力Go SDK 实现工作器管理: 深入了解worker.Options包括MaxConcurrentActivityTaskPollers、WorkerStopTimeout和StickyScheduleToStartTimeout。拦截器: 为横切关注点日志、追踪、认证实现客户端、工作器和工作流拦截器。自定义数据转换器: 集成 Protobuf、加密负载或自定义 JSON 编组。高级工作流模式持久并发: 使用workflow.Go、workflow.Channel和workflow.Selector代替原生原语。版本管理: 使用workflow.GetVersion和workflow.GetReplaySafeLogger实现安全的代码演进。大规模处理: 使用ContinueAsNew模式管理历史记录大小限制默认值50MB 或 5 万条事件。子工作流: 管理生命周期、取消以及父子信号传播。测试与可观测性测试套件精通: 使用WorkflowTestSuite进行具有确定性时间控制的单元和功能测试。模拟: 复杂的活动和子工作流模拟策略。重放测试: 针对生产事件历史验证代码更改。指标: 为工作器性能跟踪配置 Prometheus/OpenTelemetry 导出器。示例示例 1: 版本化工作流确定性// Note: imports omitted. Requires go.temporal.io/sdk/workflow, go.temporal.io/sdk/temporal, and time.funcSubscriptionWorkflow(ctx workflow.Context,userIDstring)error{// 1. Versioning for logic evolution (v1 DefaultVersion)v:workflow.GetVersion(ctx,billing_logic,workflow.DefaultVersion,2)fori:0;i12;i{ao:workflow.ActivityOptions{StartToCloseTimeout:5*time.Minute,RetryPolicy:temporal.RetryPolicy{MaximumAttempts:3},}ctxworkflow.WithActivityOptions(ctx,ao)// 2. Activity Execution (Always handle errors)err:workflow.ExecuteActivity(ctx,ChargePaymentActivity,userID).Get(ctx,nil)iferr!nil{workflow.GetLogger(ctx).Error(Payment failed,Error,err)returnerr}// 3. Durable Sleep (Time-skipping safe)sleepDuration:30*24*time.Hourifv2{sleepDuration28*24*time.Hour}iferr:workflow.Sleep(ctx,sleepDuration);err!nil{returnerr}}returnnil}示例 2: 完整的 mTLS 工作器设置funcRunSecureWorker()error{// 1. Load Client Certificate and Keycert,err:tls.LoadX509KeyPair(client.pem,client.key)iferr!nil{returnfmt.Errorf(failed to load client keys: %w,err)}// 2. Load CA Certificate for Server verification (Proper mTLS)caPem,err:os.ReadFile(ca.pem)iferr!nil{returnfmt.Errorf(failed to read CA cert: %w,err)}certPool:x509.NewCertPool()if!certPool.AppendCertsFromPEM(caPem){returnfmt.Errorf(failed to parse CA cert)}// 3. Dial Cluster with full TLS configc,err:client.Dial(client.Options{HostPort:temporal.example.com:7233,Namespace:production,ConnectionOptions:client.ConnectionOptions{TLS:tls.Config{Certificates:[]tls.Certificate{cert},RootCAs:certPool,},},})iferr!nil{returnfmt.Errorf(failed to dial temporal: %w,err)}deferc.Close()w:worker.New(c,payment-queue,worker.Options{})w.RegisterWorkflow(SubscriptionWorkflow)iferr:w.Run(worker.InterruptCh());err!nil{returnfmt.Errorf(worker run failed: %w,err)}returnnil}示例 3: Selector 与信号集成funcApprovalWorkflow(ctx workflow.Context)(string,error){varapprovedboolsignalCh:workflow.GetSignalChannel(ctx,approval-signal)// Use Selector to wait for multiple async eventss:workflow.NewSelector(ctx)s.AddReceive(signalCh,func(c workflow.ReceiveChannel,_bool){c.Receive(ctx,approved)})// Add 72-hour timeout timers.AddReceive(workflow.NewTimer(ctx,72*time.Hour).GetChannel(),func(c workflow.ReceiveChannel,_bool){approvedfalse})s.Select(ctx)if!approved{returnrejected,nil}returnapproved,nil}最佳实践✅要: 始终处理ExecuteActivity和client.Dial返回的错误。✅要: 使用workflow.Go和workflow.Channel实现并发。✅要: 迭代前对 map 键排序以保持确定性。✅要: 对持续超过 1 分钟的活动使用activity.RecordHeartbeat。✅要: 使用replayer.ReplayWorkflowHistoryFromJSON测试逻辑兼容性。❌不要: 在生产工作器中使用_吞掉错误或在log.Fatal中吞掉错误。❌不要: 在工作流函数内直接进行网络/磁盘 I/O。❌不要: 依赖原生time.Now()或rand.Int()。❌不要: 将此项应用于不需要持久性的简单 cron 任务。故障排查恐慌确定性不匹配: 通常由未经workflow.GetVersion的逻辑更改或非确定性代码例如原生 map引起。错误历史记录大小超限: 达到历史记录限制默认 5 万条事件。确保实现了ContinueAsNew。工作器挂起: 检查WorkerStopTimeout并确保所有活动都处理上下文取消。局限性不涵盖 Temporal Cloud UI 导航或 TLS 证书配置流程。不涵盖 Temporal Java、Python 或 TypeScript SDK请参考各自的专用-pro技能。假设 Temporal Server v1.20 和 Go SDK v1.25较旧的 SDK 版本可能具有不同的 API。不涵盖实验性的 Temporal 功能例如 Nexus、多集群复制。不涉及全局命名空间配置或多区域故障转移设置。不涵盖通过worker-versioning功能标志实验性进行 Temporal 工作器版本管理。资源实施手册 - 深入探讨 Go SDK 模式。测试策略 - Go 的单元、重放和集成测试。Temporal Go SDK 参考Temporal Go 示例相关技能grpc-golang- 内部传输协议和 Protobuf 设计。golang-pro- 通用 Go 性能调优和高级语法。workflow-orchestration-patterns- 与语言无关的编排策略。