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

使用 Signal 推送外部事件

使用 Signal 推送外部事件

本课解决运行中的 Workflow 如何接收审批结果、回调通知或业务事件的问题。重点不是“把消息送进来”,而是让事件重复、乱序甚至延迟到达时,Workflow 仍能按业务规则安全更新状态。

学习目标

  • 能区分 Signal 与普通 Activity、Query 的职责,并建立运行中 Workflow 的事件入口
  • 能实现幂等的 Signal 状态变更,处理重复事件和乱序事件
  • 能验证 Signal 已进入 Workflow,并识别处理逻辑中的常见边界

Signal 的职责边界

Signal 是发给正在运行的 Workflow 的异步消息入口。发送方不需要暂停等待 Workflow 返回业务结果,Workflow 收到 Signal 后可以修改自己的状态,并继续后续流程。

这使 Signal 很适合“外部事实已经发生,现在通知 Workflow”的场景,例如人工审批完成、支付渠道回调、人工补录结果。相反,读取 Workflow 当前状态通常应该使用 Query,需要执行副作用的动作则仍应放到 Activity 中。

Signal 从外部系统进入运行中 Workflow

主示例:接收审批结果

下面示例使用 Temporal Go SDK。Workflow 通过 Signal Channel 接收审批事件,并把事件转换成可验证的业务状态。示例中的 handledEvents 用于记录已经处理过的事件 ID,从而抵抗客户端重试造成的重复 Signal。

go
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:

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

预期输出

text
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 负责按确定规则吸收事实并推进自己的状态。

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

目录与阅读设置

阅读设置

17

记录一个想法

使用 Signal 推送外部事件

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

登录哪都通