1. 课程导论：Temporal平台简介、工作流与活动概念、OpenAPI扩展的价值与目标
1.1 为什么需要Temporal？
在微服务与分布式系统日益复杂的今天，开发者面临的核心挑战并非业务逻辑本身，而是如何可靠地编排跨服务、跨网络、可能耗时数秒甚至数月的异步流程。传统方案（消息队列、状态机、数据库轮询）往往将状态管理、重试逻辑、超时处理与业务代码深度耦合，导致系统脆弱且难以维护。
Temporal 是一个开源的、企业级的工作流引擎，它通过提供持久化执行（Durable Execution）能力，将应用程序的编排逻辑与执行状态完全解耦。开发者只需编写普通代码，Temporal 即可保证工作流在遇到进程崩溃、网络分区、机器重启等故障后，从最后一个稳定点继续执行，仿佛故障从未发生。
核心洞察： Temporal 将“时间”和“状态”从应用代码中抽离，让开发者专注于业务逻辑，而非基础设施的可靠性。
1.2 核心概念：工作流（Workflow）与活动（Activity）
Temporal 的编程模型围绕两个基本抽象构建：
| 概念 | 角色 | 关键特性 | 类比 |
|---|---|---|---|
| 工作流（Workflow） | 编排者 | 定义流程顺序、分支、循环、等待； 具有确定性（Deterministic）； 可长时间运行（数秒至数年） |
乐谱（总谱） |
| 活动（Activity） | 执行者 | 封装具体的业务逻辑（RPC调用、数据库写入、文件处理）； 可重试、可超时； 可包含副作用（非确定性） |
乐器演奏 |
- 工作流（Workflow）： 负责编排。它使用
await或yield调用活动，并处理超时、重试、补偿（Saga）等逻辑。工作流代码必须是确定性的——相同的输入必须产生相同的执行路径，不依赖系统时间、随机数或外部状态。 - 活动（Activity）： 负责执行。它包含真正的业务逻辑，可以调用数据库、第三方API、发送邮件等。Temporal 会自动记录活动的输入/输出，并在失败时根据配置进行重试。
最佳实践： 将工作流视为“编排层”，活动视为“执行层”。工作流不应包含任何 I/O 操作；所有 I/O 都应封装在活动中。
1.3 Temporal 平台架构概览
下图展示了 Temporal 平台的核心组件及其交互关系：
架构要点说明：
- 应用客户端： 通过 SDK 启动工作流、发送信号（Signal）、查询（Query）状态。
- Temporal Server： 无状态网关 + 有状态引擎，负责接收命令、维护事件历史、调度任务。
- Worker： 用户部署的进程，注册工作流和活动的实现代码，从 Server 拉取任务并执行。
- 持久化存储： 保存所有工作流的事件历史（Event History），是实现故障恢复的基础。
1.4 OpenAPI扩展的价值与目标
尽管 Temporal 提供了强大的编排能力，但在实际落地中，团队往往面临以下痛点：
- 集成门槛高： 调用外部 REST API 需要手动编写活动代码，处理认证、重试、序列化。
- 缺乏标准化： 每个团队对 API 调用的错误处理、超时策略、日志记录方式各异。
- 难以复用： 已有的 OpenAPI（Swagger）规范无法直接映射为 Temporal 活动。
本课程提出的 OpenAPI 工作流扩展 旨在解决上述问题，其核心价值如下：
| 维度 | 传统方式 | OpenAPI 扩展方式 |
|---|---|---|
| API 集成 | 手动编写 HTTP 客户端代码，处理序列化/反序列化 | 基于 OpenAPI 规范自动生成活动定义 |
| 错误处理 | 每个活动各自实现重试、超时、熔断 | 统一由扩展层管理，支持声明式策略 |
| 可观测性 | 分散的日志和指标 | 自动注入链路追踪、事件记录 |
| 开发效率 | 数小时编写一个活动 | 数分钟完成 API 到活动的映射 |
注意： OpenAPI 扩展并非替代 Temporal SDK，而是在 SDK 之上构建的一层声明式适配层。它让开发者能够以配置文件或注解的方式，将 OpenAPI 端点直接暴露为 Temporal 活动，从而大幅降低集成成本。
1.5 课程目标与学习路径
通过本课程，你将掌握：
- 理解 Temporal 核心模型： 工作流、活动、信号、查询、重试策略。
- 掌握 OpenAPI 规范： 路径、参数、请求体、响应、安全方案。
- 构建扩展框架： 设计从 OpenAPI 到 Temporal 活动的映射引擎。
- 实现高级特性： 动态路由、批量调用、补偿事务（Saga）、长轮询适配。
- 生产化部署： 性能调优、监控告警、多租户隔离。
下图展示了本课程的知识体系结构：