服务注册与分布式协调 / 系统课时
使用 Nexus 连接跨服务能力
使用 Nexus 连接跨服务能力
本课解决跨命名空间、跨团队调用 Temporal 能力时的耦合问题:调用方只依赖稳定的 Nexus Service 契约,通过 Endpoint 路由到服务实现,最终把远程能力纳入可追踪、可重试的工作流编排。
学习目标
- 理解 Nexus Service、Operation、Endpoint 与处理方 Worker 的职责边界
- 能用 Go SDK 定义跨团队契约并从 Workflow 发起 Nexus Operation
- 能为 Endpoint 和异步 Operation 设计稳定的身份与超时边界
先建立跨服务模型
Nexus 的关键价值不是再造一套 RPC,而是把“远程能力调用”放进 Temporal 的持久执行模型。调用方 Workflow 不直接依赖处理方的 Task Queue、内部 Workflow 名称或实现代码,而是依赖 Service 与 Operation 契约;Endpoint 再把请求路由到目标 Namespace 和 Task Queue。

Endpoint 是调用方看到的稳定入口。它把“调用谁”与“怎么实现”分离,因此处理方可以更换 Worker、Task Queue 或内部 Workflow,只要对外的 Service 与 Operation 契约保持兼容即可。实际服务通常由一个或多个 Operation 组成,每个 Operation 再决定执行逻辑是同步完成,还是转交给长期运行的 Temporal Workflow。
对于可能等待数据库、第三方 API 或其他不稳定依赖的能力,优先使用异步 Operation,让请求先取得 Operation 身份,再由处理方 Workflow 持久执行。这样调用方不会把一次远程调用的网络等待直接等同于业务事务本身。
定义可演进的 Service 契约
下面以 Go SDK 为例。把 Service 名称、Operation 名称和输入类型单独放在共享契约包中,调用方只需要依赖这个包,而不需要引入处理方的业务实现。
package greeting
const (
HelloServiceName = "greeting-service"
HelloOperationName = "say-hello"
)
type HelloInput struct {
Name string
}预期结果
调用方和处理方都可以引用同一份 greeting 契约;Service 与 Operation 名称保持一致,输入类型也保持一致。接着在处理方注册异步 Nexus Operation。下面是片段示例,假设 HelloHandlerWorkflow 已经实现真正的业务流程;关键点是使用稳定的 Workflow ID,避免 Nexus 请求在重试或重复投递时无界地产生重复执行。
var HelloOperation = temporalnexus.NewWorkflowRunOperation(
HelloOperationName,
HelloHandlerWorkflow,
func(ctx context.Context, input HelloInput, options nexus.StartOperationOptions) (client.StartWorkflowOptions, error) {
return client.StartWorkflowOptions{
ID: options.RequestID,
}, nil
},
)
service := nexus.NewService(HelloServiceName)
if err := service.Register(HelloOperation); err != nil {
return err
}
w.RegisterNexusService(service)预期结果
处理方 Worker 成功注册 Nexus Service;收到 say-hello Operation 后,由 HelloHandlerWorkflow 持久执行具体业务。从 Workflow 发起 Nexus Operation
调用方 Workflow 通过 Endpoint 名称和 Service 名称创建 Nexus Client,再执行 Operation。ScheduleToCloseTimeout 应覆盖一次 Nexus Operation 从调度到最终完成的业务窗口,而不是只覆盖一次网络请求。
func CallerWorkflow(ctx workflow.Context, name string) (string, error) {
client := workflow.NewNexusClient(
"greeting-endpoint",
HelloServiceName,
)
future := client.ExecuteOperation(
ctx,
HelloOperationName,
HelloInput{Name: name},
workflow.NexusOperationOptions{
ScheduleToCloseTimeout: 10 * time.Second,
},
)
var result string
if err := future.Get(ctx, &result); err != nil {
return "", err
}
return result, nil
}预期结果
CallerWorkflow 执行 say-hello 后收到处理方 Workflow 返回的业务结果;如果处理方暂时不可用,调用关系仍由 Temporal 的持久执行机制管理,而不是依赖一次普通 RPC 连接始终保持在线。创建 Endpoint 并检查边界
Endpoint 的目标应明确指向处理方 Namespace 与 Task Queue。例如下面的 CLI 操作把名为 greeting-endpoint 的入口路由到指定 Worker。
temporal operator nexus endpoint create \
--name greeting-endpoint \
--target-namespace <NAMESPACE> \
--target-task-queue <TASK_QUEUE>预期结果
Nexus Endpoint greeting-endpoint 创建成功,并记录目标 Namespace=<NAMESPACE>、Task Queue=<TASK_QUEUE>。真正上线前,还要把契约兼容性放在 Endpoint 配置之外考虑。新增可选字段通常比修改字段含义安全;已经被调用方依赖的 Operation 名称不要随意复用到不同语义。对于异步 Operation,还应明确超时、幂等键、可重试错误与业务失败的区别。
让跨团队契约可治理
一个健康的 Nexus 接口至少要能回答四个问题:输入如何唯一标识业务请求,成功结果是什么,哪些错误允许调用方重试,以及处理方多久完成或进入超时。把这些约束写进共享契约和接口说明,而不是依赖某个团队成员熟悉的内部实现。
当处理方升级内部 Workflow、拆分服务或迁移 Task Queue 时,只要 Endpoint 与 Service Contract 继续兼容,调用方 Workflow 可以保持不变。Nexus 因而更适合组织边界清晰、实现仓库独立、生命周期不同的跨服务能力编排。