服务注册与分布式协调 / 系统课时
使用 Signal 推送外部事件
使用 Signal 推送外部事件
本课解决运行中的 Workflow 如何接收审批结果、回调通知或业务事件的问题。重点不是“把消息送进来”,而是让事件重复、乱序甚至延迟到达时,Workflow 仍能按业务规则安全更新状态。
学习目标
- 能区分 Signal 与普通 Activity、Query 的职责,并建立运行中 Workflow 的事件入口
- 能实现幂等的 Signal 状态变更,处理重复事件和乱序事件
- 能验证 Signal 已进入 Workflow,并识别处理逻辑中的常见边界
Signal 的职责边界
Signal 是发给正在运行的 Workflow 的异步消息入口。发送方不需要暂停等待 Workflow 返回业务结果,Workflow 收到 Signal 后可以修改自己的状态,并继续后续流程。
这使 Signal 很适合“外部事实已经发生,现在通知 Workflow”的场景,例如人工审批完成、支付渠道回调、人工补录结果。相反,读取 Workflow 当前状态通常应该使用 Query,需要执行副作用的动作则仍应放到 Activity 中。

主示例:接收审批结果
下面示例使用 Temporal Go SDK。Workflow 通过 Signal Channel 接收审批事件,并把事件转换成可验证的业务状态。示例中的 handledEvents 用于记录已经处理过的事件 ID,从而抵抗客户端重试造成的重复 Signal。
package workflow
import (
"time"
"go.temporal.io/sdk/workflow"
)
type ApprovalEvent struct {
EventID string
Status string
At time.Time
}
type ApprovalState struct {
Status string
LastEventAt time.Time
HandledEvent map[string]struct{}
}
func ApprovalWorkflow(ctx workflow.Context) error {
signalCh := workflow.GetSignalChannel(ctx, "approval-result")
state := ApprovalState{Status: "PENDING", HandledEvent: map[string]struct{}{}}
for state.Status == "PENDING" {
var event ApprovalEvent
workflow.Selector(ctx).AddReceive(signalCh, func(c workflow.ReceiveChannel, more bool) {
c.Receive(ctx, &event)
}).Select(ctx)
// EventID 作为幂等键;重复 Signal 不再次修改业务状态。
if _, exists := state.HandledEvent[event.EventID]; exists {
continue
}
// 事件到达可能乱序,只有更新事件时间不早于当前状态时才推进状态。
if !event.At.Before(state.LastEventAt) {
state.Status = event.Status
state.LastEventAt = event.At
}
state.HandledEvent[event.EventID] = struct{}{}
}
return nil
}预期结果
上述片段的 Workflow 会持续等待 approval-result Signal。第一次处理新的 EventID 时更新状态;同一个 EventID 再次到达时直接忽略;较早事件在更晚事件之后到达时,不会把状态倒退到旧版本。
发送 Signal 的业务服务可以使用 Workflow ID、Signal Name 和事件负载调用 Temporal Client:
package main
import (
"context"
"log"
"time"
"go.temporal.io/sdk/client"
)
func main() {
c, err := client.Dial(client.Options{HostPort: "<TEMPORAL_ADDRESS>"})
if err != nil {
log.Fatal(err)
}
defer c.Close()
event := struct {
EventID string
Status string
At time.Time
}{
EventID: "approval-<ID>",
Status: "APPROVED",
At: time.Now().UTC(),
}
if err := c.SignalWorkflow(
context.Background(),
"approval-<ID>",
"",
"approval-result",
event,
); err != nil {
log.Fatal(err)
}
log.Println("signal sent")
}预期输出
signal sent这里的 SignalWorkflow 只表示 Signal 已被发送给指定 Workflow;它不等价于“业务状态已经处理完成”。真正的业务结果应由 Workflow 自己的状态、后续 Activity 或 Query 验证。
重复与乱序为什么必须显式处理
Signal 是消息输入,不应假设“同一事件只会到达一次”或“事件一定按业务时间顺序到达”。外部系统可能重试请求,同一审批结果可能产生多次通知,不同来源的事件也可能交错抵达。
最实用的幂等设计是为外部事件分配稳定的 EventID。Workflow 保存已处理事件 ID;再次收到相同事件时不重复执行状态变更。这样做时,EventID 必须来自业务事实本身,而不是每次重试临时生成的新随机值。
乱序处理则要先定义业务规则。有些状态只允许单向推进,例如 PENDING → APPROVED;这时可以保存事件版本、业务序号或事件时间,并拒绝更旧的事件。不要仅凭“收到得更晚”判断事件更新,因为网络到达时间不等于业务发生时间。
验证与故障边界
验证时至少覆盖三个情况:同一个 EventID 连续发送两次、先发送较新的业务事件再发送较旧事件,以及 Workflow 已结束后继续发送 Signal。
前两种情况验证的是 Workflow 内部的幂等与顺序规则;最后一种情况则属于生命周期边界,不能用 Workflow 内部逻辑解决。客户端发送 Signal 时应记录调用错误,并根据业务语义决定重试、忽略还是转入补偿流程。
实际业务中,Signal Payload 也应尽量包含足够的业务事实,而不是只传一个“执行某动作”的命令名。Workflow 根据事实计算状态,通常比把大量业务判断藏在发送端更容易保持可恢复性与可审计性。
把 Signal 设计成“稳定事件 ID + 明确业务时间或版本 + 幂等状态变更”后,审批、支付回调和异步通知都可以复用同一可靠模式:外部系统负责提交事实,Workflow 负责按确定规则吸收事实并推进自己的状态。