服务注册与分布式协调 / 系统课时
初始化 Go SDK 项目并连接 Client
初始化 Go SDK 项目并连接 Client
这一课把一个空目录变成可连接 Temporal 的 Go 项目:安装 Go SDK、配置本地服务地址与 Namespace,并通过健康检查确认程序确实能访问 Temporal 服务。完成后,你会得到一个可复用的 Client 初始化入口。
学习目标
- 初始化 Go Module 并引入 Temporal Go SDK
- 使用
client.DialContext配置服务地址和 Namespace - 通过健康检查区分连接成功与常见配置错误
准备工程与依赖
需要先有一个正在运行的 Temporal 服务。本文按本地开发环境使用 localhost:7233,Namespace 使用 default;如果你的环境不同,只需替换后面的两个配置值。
在空目录中初始化模块并安装 SDK:
mkdir temporal-demo
cd temporal-demo
go mod init example.com/temporal-demo
go get go.temporal.io/sdk@latest
go list -m go.temporal.io/sdk预期输出如下。依赖下载日志会随缓存和版本变化,关键是最后能列出 go.temporal.io/sdk;实际版本号以本机解析结果为准。
go: creating new go.mod: module example.com/temporal-demo
go.temporal.io/sdk v<VERSION>此时 go.mod 已记录 Temporal SDK 依赖,后续代码可以直接导入 go.temporal.io/sdk/client。
建立 Client 并主动验证连接
创建 main.go。示例用五秒超时包住拨号和健康检查,避免地址写错时程序长时间等待。
package main
import (
"context"
"fmt"
"log"
"time"
"go.temporal.io/sdk/client"
)
const (
temporalAddress = "localhost:7233"
temporalNamespace = "default"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
// DialContext 会主动连接服务,失败时立即把连接问题暴露出来。
c, err := client.DialContext(ctx, client.Options{
HostPort: temporalAddress,
Namespace: temporalNamespace,
})
if err != nil {
log.Fatalf("connect Temporal: %v", err)
}
defer c.Close()
// 再发送一次显式健康检查,确认 gRPC 服务可以响应请求。
if _, err := c.CheckHealth(ctx, &client.CheckHealthRequest{}); err != nil {
log.Fatalf("health check: %v", err)
}
fmt.Printf("connected to Temporal at %s, namespace=%s\n",
temporalAddress, temporalNamespace)
}运行程序:
go run .预期输出:
connected to Temporal at localhost:7233, namespace=default如果能看到这一行,说明 SDK 依赖可用、地址可达,而且应用已经成功访问 Temporal 服务。Client 内部维护连接等资源,服务程序通常应长期复用一个实例,并在进程退出时调用 Close,不要为每个业务请求重新创建 Client。
理解地址与 Namespace 的边界
HostPort 决定程序连接哪个 Temporal Frontend;本地开发环境通常是 localhost:7233。Namespace 则决定后续 Workflow、Schedule、Visibility 等命令落在哪个逻辑隔离空间,两者解决的是不同问题。
健康检查只证明服务可达,并不会证明某个 Namespace 一定存在。因此地址正确但 Namespace 拼错时,本程序仍可能通过健康检查,直到第一次发送 Namespace 相关请求时才出现 NamespaceNotFound。这也是排错时必须把“网络连接”和“业务命名空间”分开检查的原因。
连接失败时按顺序检查
出现 connection refused 时,优先确认 Temporal 服务是否启动、端口是否为 7233;出现 context deadline exceeded 时,再检查地址、容器端口映射、防火墙或代理。若后续业务调用返回 NamespaceNotFound,则检查 Namespace 拼写和目标服务中是否真的创建了该 Namespace。
本地开发通常不需要 TLS;连接 Temporal Cloud 或受保护的生产集群时,还需要在 client.Options 中补充 TLS 与认证配置。无论环境如何,先让 Client 的连接地址、Namespace 和验证请求形成一个可重复的小闭环,再继续编写 Worker 和 Workflow。