服务注册与分布式协调 / 系统课时

初始化 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:

bash
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;实际版本号以本机解析结果为准。

text
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。示例用五秒超时包住拨号和健康检查,避免地址写错时程序长时间等待。

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)
}

运行程序:

bash
go run .

预期输出:

text
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。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

初始化 Go SDK 项目并连接 Client

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通