3. Temporal 开发环境搭建：Server、CLI 与 SDK 配置

搭建可靠的 Temporal 开发环境是进行工作流开发的第一步。本章将指导你完成 Temporal Server 的安装与启动、Temporal CLI 的常用操作，以及 Go 和 Java SDK 的工程配置。完成本环境搭建后，你将拥有一个可本地运行的工作流调试平台。

3.1 Temporal Server 安装

Temporal Server 支持多种部署方式：本地开发推荐使用 Docker Compose，生产环境建议使用 Kubernetes 或 Temporal Cloud。以下为本地开发环境的快速安装步骤。

3.1.1 使用 Docker Compose 一键启动

Temporal 官方提供了 docker-compose.yml 文件，包含 Server、Web UI 和 Cassandra/PostgreSQL 等依赖组件。

# 1. 克隆官方仓库
git clone https://github.com/temporalio/docker-compose.git
cd docker-compose

# 2. 启动所有服务（默认使用 Cassandra）
docker compose up -d

# 3. 验证服务状态
docker compose ps

启动成功后，你将获得以下核心服务端口：

3.1.2 验证 Server 运行状态

打开浏览器访问 http://localhost:8080，你将看到 Temporal Web UI 的命名空间列表页面。默认存在 default 命名空间，表示 Server 已正常运行。

3.2 Temporal CLI 使用

Temporal CLI 是官方提供的命令行工具，用于管理工作流、任务队列、命名空间等资源。安装方式如下：

# macOS (Homebrew)
brew install temporal

# Linux (curl 安装)
curl -sSf https://temporal.download/cli.sh | sh

# Windows (Scoop)
scoop bucket add temporal https://github.com/temporalio/scoop-temporal.git
scoop install temporal

3.2.1 核心命令速查

3.2.2 常用操作示例

以下命令演示了如何通过 CLI 与运行中的 Temporal Server 交互：

# 1. 注册命名空间
temporal namespace register --namespace my-workflow-ns

# 2. 查看命名空间详情
temporal namespace describe --namespace my-workflow-ns

# 3. 启动一个工作流（假设 Worker 已运行）
temporal workflow start \
  --task-queue hello-world-queue \
  --workflow-id my-first-workflow \
  --type GreetWorkflow \
  --input '"Temporal"' \
  --namespace my-workflow-ns

# 4. 查看工作流执行结果
temporal workflow show --workflow-id my-first-workflow --namespace my-workflow-ns

3.3 Go SDK 配置

Go SDK 是 Temporal 官方支持最成熟的客户端之一。以下步骤演示如何在一个 Go 项目中集成 Temporal SDK。

3.3.1 初始化 Go 模块并安装 SDK

# 创建项目目录
mkdir temporal-go-demo && cd temporal-go-demo
go mod init temporal-go-demo

# 安装 Temporal Go SDK
go get go.temporal.io/sdk@v1.26.0

3.3.2 编写 Worker 与 Client 代码

以下是一个最小化的 Worker 启动代码，连接到本地 Server 并监听任务队列：

package main

import (
    "log"
    "go.temporal.io/sdk/client"
    "go.temporal.io/sdk/worker"
)

func main() {
    // 1. 创建 Temporal Client
    c, err := client.Dial(client.Options{
        HostPort:  "localhost:7233",
        Namespace: "default",
    })
    if err != nil {
        log.Fatalln("无法创建 Temporal Client", err)
    }
    defer c.Close()

    // 2. 创建 Worker
    w := worker.New(c, "hello-world-queue", worker.Options{})

    // 3. 注册工作流与活动
    w.RegisterWorkflow(GreetWorkflow)
    w.RegisterActivity(GreetActivity)

    // 4. 启动 Worker（阻塞）
    err = w.Run(worker.InterruptCh())
    if err != nil {
        log.Fatalln("Worker 运行失败", err)
    }
}

3.4 Java SDK 配置

Java SDK 适用于 Spring Boot 或纯 Java 项目。以下以 Maven 项目为例进行配置。

3.4.1 Maven 依赖配置

在 pom.xml 中添加 Temporal SDK 依赖：

<dependency>
    <groupId>io.temporal</groupId>
    <artifactId>temporal-sdk</artifactId>
    <version>1.22.0</version>
</dependency>

3.4.2 编写 Worker 启动类

import io.temporal.client.WorkflowClient;
import io.temporal.serviceclient.WorkflowServiceStubs;
import io.temporal.worker.Worker;
import io.temporal.worker.WorkerFactory;

public class TemporalWorker {
    public static void main(String[] args) {
        // 1. 创建 gRPC 连接
        WorkflowServiceStubs service = WorkflowServiceStubs
            .newInstance(WorkflowServiceStubsOptions.newBuilder()
                .setTarget("localhost:7233")
                .build());

        // 2. 创建 WorkflowClient
        WorkflowClient client = WorkflowClient.newInstance(service,
            WorkflowClientOptions.newBuilder()
                .setNamespace("default")
                .build());

        // 3. 创建 WorkerFactory 并启动 Worker
        WorkerFactory factory = WorkerFactory.newInstance(client);
        Worker worker = factory.newWorker("hello-world-queue");
        worker.registerWorkflowImplementationTypes(GreetWorkflowImpl.class);
        worker.registerActivitiesImplementations(new GreetActivityImpl());

        factory.start();
        System.out.println("Worker 已启动，等待任务...");
    }
}

3.5 环境验证清单

完成上述配置后，请按以下清单验证环境是否就绪：

• Server 状态： curl -s http://localhost:7233/health 返回 {"status":"SERVING"}
• Web UI 可访问： 浏览器打开 http://localhost:8080 显示命名空间列表
• CLI 连通性： temporal workflow list --namespace default 不报错
• Go Worker 启动： 运行 Worker 程序后，控制台无连接错误
• Java Worker 启动： 运行 Worker 程序后，输出 "Worker 已启动" 日志

3.6 本章小结

通过本章的学习，你已完成 Temporal 开发环境的全链路搭建：

• 使用 Docker Compose 启动了包含 Server、Web UI 和存储的完整环境
• 掌握了 Temporal CLI 的安装与核心命令
• 配置了 Go SDK 和 Java SDK，并编写了最小 Worker 启动代码
• 理解了 SDK 与 Server 之间的 gRPC 交互流程