服务注册与分布式协调 / 系统课时
编写第一个 Workflow
编写第一个 Workflow
这一课从最小 Go 函数开始,定义一个可被 Temporal Worker 执行的 Workflow,并明确参数、返回值、注册名称与调用入口之间的关系。完成后,你能写出一个结构正确、可以交给 Worker 注册的第一个 Workflow。
学习目标
- 掌握 Go Workflow 函数的基本签名与输入输出规则
- 学会向 Worker 注册 Workflow,并理解注册名称的来源
- 区分 Workflow 定义、Worker 注册和客户端启动三者的职责
先写最小 Workflow
Temporal Go SDK 的 Workflow 本质上是一个符合约定的 Go 函数。它接收 workflow.Context,可以接收业务参数,并返回业务结果和 error。Workflow 函数本身负责描述可靠编排逻辑,而不是直接承担 Worker 注册或客户端启动职责。
下面只保留一个主示例,假设项目已经使用 Go Modules,并依赖当前 Temporal Go SDK。
package workflowdemo
import "go.temporal.io/sdk/workflow"
// GreetingWorkflow 是业务编排入口,参数和返回值会参与 Workflow 类型契约。
func GreetingWorkflow(ctx workflow.Context, name string) (string, error) {
return "Hello, " + name, nil
}这是一个片段示例:它依赖 Temporal Worker 执行环境,但已经是完整合法的 Workflow 函数,可以直接放入一个 Go 包中。这里没有普通 context.Context,而是必须使用 Temporal 提供的 workflow.Context。
预期结果
Workflow 函数编译通过,并可以作为 Temporal Worker 的 Workflow 定义进行注册。参数、返回值与 Workflow 名称
Workflow 的参数应采用 SDK 能够序列化的数据类型。对于最小示例,string 很合适;真实项目通常会进一步定义结构体,把业务输入集中放在一个明确的数据类型中。
返回值可以是业务结果和 error。例如 GreetingWorkflow 返回一个 string,客户端在 Workflow 成功结束后即可取得该结果。错误则用于表示当前 Workflow 的失败结果,而不是随意把外部副作用直接写进 Workflow 函数。
注册时可以使用函数默认名称,也可以显式指定名称。显式名称适合需要稳定、可读的 Workflow 类型名称的场景,尤其是在代码重构但希望继续维持既有 Workflow 类型标识时,更容易进行治理。
把 Workflow 注册给 Worker
定义函数还不够。Worker 必须知道它负责执行哪些 Workflow,因此需要显式注册。注册发生在 Worker 启动配置阶段,客户端之后才能向对应 Task Queue 发起执行请求。
下面是注册动作的核心片段。
package workflowdemo
import (
"go.temporal.io/sdk/worker"
"example.com/workflowdemo/workflowdemo"
)
func registerWorkflows(w worker.Worker) {
// Worker 必须注册实际要执行的 Workflow 实现。
w.RegisterWorkflow(workflowdemo.GreetingWorkflow)
}这是片段示例,worker.Worker 的具体创建方式取决于你的服务地址、Namespace、Task Queue 和 Worker 配置。这里最重要的是:Workflow 定义写业务逻辑,Worker 注册建立“类型名称 → 实现”的映射。
预期结果
Worker 启动后能够识别 GreetingWorkflow;收到对应 Workflow Task 时,可以找到已注册的实现。默认名称与显式名称怎么选
默认注册方式通常直接从 Workflow 函数得到可识别的类型名称,适合简单项目。需要稳定对外名称时,可以使用 RegisterWorkflowWithOptions 显式设置名称。
例如下面的配置让注册名称不依赖 Go 函数名本身。
w.RegisterWorkflowWithOptions(
workflowdemo.GreetingWorkflow,
workflow.RegisterOptions{Name: "GreetingWorkflow"},
)这是片段示例,需要放在已经创建好的 worker.Worker 上下文中,并导入 go.temporal.io/sdk/workflow。显式名称最重要的价值不是让代码更短,而是让 Workflow 类型名称成为可以独立治理的契约。
预期结果
Worker 注册表中,GreetingWorkflow 的 Workflow 类型名称固定为 GreetingWorkflow。Workflow、Worker、Client 的职责边界
写第一个 Workflow 时,最容易把三个角色混在一起。Workflow 是“执行什么逻辑”的定义;Worker 是“由哪个进程负责执行这些 Workflow”的运行载体;Client 则负责向 Temporal 发起启动、查询、Signal 等操作。
因此,不能因为已经写好了 Workflow 函数,就认为它会自动运行。必须有 Worker 注册该 Workflow,并且实际环境中还需要有客户端启动执行请求。这样从定义到执行的链路才完整。
开发阶段可以先验证“函数定义和注册”是否正确,再验证 Worker 与 Temporal Service 的连接,最后验证客户端启动结果。每一层都明确职责,后面遇到“Workflow 找不到”“Task Queue 没有消费者”或“代码改了但历史不能兼容”等问题时,定位会更直接。
第一个 Workflow 不需要一开始就加入复杂 Activity、Signal 或重试策略。先保证函数签名正确、注册成功、类型名称明确,再逐步把真实编排逻辑放进去,是最稳妥的起点。