> **摘要**：Structured Streaming 是 Spark 2.x 之后官方主推的流计算引擎，它把"流"抽象成一张无限追加的表，让你用写批处理 SQL 的方式写实时任务，还顺带解决了事件时间、迟到数据和端到端 Exactly-Once 这三座大山。本文从编程模型、输出模式、水位线、状态管理和容错语义五个维度把它的核心设计讲透，最后给出与 DStream 的对比和选型建议。
>
> **关键词**：Structured Streaming, Spark, 结构化流, 流批一体, 增量查询, Watermark, StateStore, Exactly-Once

---

## 一、先说结论：它到底解决了什么问题

在 Structured Streaming 出现之前，Spark Streaming（DStream）的做法是"把流切成小批"——每隔一个 batchInterval 攒一个 RDD，然后走批处理。这个模型有两个绕不开的痛点：

- **API 割裂**：流用 DStream API，批用 DataFrame/SQL，同一套业务逻辑要写两遍，优化器（Catalyst）和钨丝计划（Tungsten）的红利流侧吃不到；
- **语义要用户自己扛**：事件时间、迟到数据、端到端一致性，全得业务代码自己想办法。

Structured Streaming 的思路反过来了：**不是把流切成批，而是把流看成一张永远在追加行的表**。你在"表"上写的每一条 SQL，引擎都会自动转成增量执行的流式查询。流批不再是两套 API，而是同一套查询的两种执行方式——这就是所谓的"流批一体"。

![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-2482016/89a94ddf29f47c64c0fd290392f04840.png)

## 二、核心模型：Input Table → Query → Result Table

整个模型只有三个概念，记住这三张表就抓住了主干：

1. **Input Table（输入表）**：数据源（Kafka、文件、Socket……）里每条到达的数据，都相当于往这张表里 INSERT 一行新记录。它是无界的、只增不减的。
2. **Query（查询）**：你在输入表上定义的转换逻辑——`select`、`filter`、`groupBy`、`window`，和静态 DataFrame 的写法一模一样。
3. **Result Table（结果表）**：查询逻辑作用在输入表上得到的"当前结果"。它同样是逻辑上的表，引擎每隔一个触发间隔（Trigger）就用新到的数据对它做一次增量更新。

关键点在于：**引擎并不会真的物化整张输入表**。它只从 Source 读最新一段数据，结合保留的中间状态（比如累计到此刻的 count）算出新的结果，然后把源数据丢弃。状态只保留"维持结果正确所需的最小集合"，这是它能跑 7×24 小时的关键。

最后一个概念是 **Output（输出）**：Result Table 更新后，要把"变化的行"写到外部存储（Sink）。写多少、怎么写，由输出模式决定。

## 三、三种输出模式与触发方式

### 3.1 输出模式（Output Mode）

| 模式 | 语义 | 适用场景 |
|---|---|---|
| Complete | 每次把整张 Result Table 全量写出 | 小结果集的聚合（如全量词频），Sink 自己处理覆盖 |
| Append | 只写 Result Table 中新增的行 | 无聚合或结果行不会回改的查询（最常用） |
| Update | 只写自上次触发后被更新的行 | 聚合且希望下游只接收变更（Spark 2.1.1+） |

选错模式会直接报错——比如对聚合查询用 Append 是不允许的（除非你加了 watermark 且聚合键带事件时间），引擎在分析阶段就会拦住你。这是好事：**把语义错误暴露在启动时，而不是凌晨三点的生产事故里**。

### 3.2 触发器（Trigger）

触发器决定"多久算一次增量"：

```scala
// 默认：微批，前一批处理完立刻开始下一批
val query = wordCounts.writeStream
  .outputMode("complete")
  .format("console")
  .start()

// 固定间隔微批
.trigger(Trigger.ProcessingTime("5 seconds"))

// 只跑一批就退出（适合定时任务场景）
.trigger(Trigger.Once())

// 攒够就批跑、没数据就休眠（Spark 3.x+，成本友好）
.trigger(Trigger.AvailableNow())
```

另外还有实验性的 `Trigger.Continuous("1 second")`，走连续处理而不是微批，延迟能压到毫秒级，但只支持 map/filter 这类无状态算子，生产使用要谨慎评估。

## 四、一个最小可运行示例

官方的经典例子：从 Socket 读文本行，做实时词频统计。核心代码不到 10 行：

```scala
import org.apache.spark.sql.SparkSession

val spark = SparkSession.builder
  .appName("StructuredNetworkWordCount")
  .getOrCreate()
import spark.implicits._

// 1. 定义输入表：localhost:9999 的文本流
val lines = spark.readStream
  .format("socket")
  .option("host", "localhost")
  .option("port", 9999)
  .load()

// 2. 定义查询：拆词、分组计数（和批处理写法完全一致）
val words = lines.as[String].flatMap(_.split(" "))
val wordCounts = words.groupBy("value").count()

// 3. 启动流式查询，结果全量打到控制台
val query = wordCounts.writeStream
  .outputMode("complete")
  .format("console")
  .start()

query.awaitTermination()
```

用 `nc -lk 9999` 起个数据源就能跑。注意第 2 步的代码——把它换成读 Hive 表的 `spark.read.table(...)`，其余一行都不用改。这就是"流批同一套 API"最直观的体现。

## 五、事件时间与水位线：迟到数据的解法

实时系统里，"数据什么时候产生的"（event-time）和"数据什么时候到的"（processing-time）经常对不上——设备断网重连、Kafka 消费积压，都会让数据迟到。

Structured Streaming 的优雅之处在于：**事件时间就是表里的一列普通字段**，基于事件时间的窗口聚合只是按这列做分组而已：

```scala
// 按事件时间开 10 分钟窗口统计，允许最多迟到 10 分钟
val windowedCounts = events
  .withWatermark("eventTime", "10 minutes")
  .groupBy(window($"eventTime", "10 minutes"), $"deviceId")
  .count()
```

`withWatermark` 声明的是"我最多容忍迟到多久"。引擎内部维护一个随数据推进的水位线（Watermark = 当前最大事件时间 - 容忍阈值）：

- 事件时间早于水位线的迟到数据 → 直接丢弃；
- 水位线一旦越过某个窗口的结束时间 → 该窗口的状态就可以从 StateStore 里清掉。

这就回答了流计算里最难的两个问题：**"窗口什么时候可以出结果"和"状态什么时候可以删"**，而且语义和引擎实现是绑定的，不用业务代码操心。

![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-2482016/cb52f54385c98809baed7bc057ff7f36.png)


## 六、容错与端到端 Exactly-Once

Structured Streaming 的设计目标之一就是**任意故障下的端到端精确一次语义**，它靠三个组件配合实现：

1. **可重放的 Source**：每个流式 Source 都带 offset（Kafka offset、文件位点……），记录了"读到哪了"，故障后可以重放；
2. **Checkpoint + WAL（预写日志）**：引擎把每个微批的 offset 范围和中间状态，先写进可靠存储（HDFS/OSS）里的 checkpoint 目录，再开始计算。Driver 挂了重启后，从 checkpoint 恢复到断点继续跑；
3. **幂等的 Sink**：重放意味着同一段数据可能被算两次，Sink 必须支持幂等写入（或者像 Delta Lake 那样支持事务），保证重复写不会产生脏数据。

三者齐备，端到端 Exactly-Once 才成立。实践中两个要点：

```scala
// checkpoint 目录是流任务的"命根子"，必须指向可靠存储
val query = df.writeStream
  .option("checkpointLocation", "hdfs://namenode:8020/chk/wordcount")
  .start()
```

- checkpoint 里存了查询的元信息和状态，**改了代码逻辑（尤其是有状态算子）不能直接复用旧 checkpoint 重启**，要么保证兼容性，要么换目录重新算。

![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-2482016/cf118a97f6296a38090283fe6c98216a.png)


## 七、状态管理：StateStore 的两种实现

聚合、去重、`mapGroupsWithState` 这些有状态算子，背后都是 **StateStore**——一个分布在 Executor 上、按分区组织的 KV 存储，版本化地与 checkpoint 协同。

Spark 提供两种内置实现：

| 维度 | HDFS 默认实现 | RocksDB StateStore（Spark 3.2+） |
|---|---|---|
| 状态存放 | JVM 堆内 HashMap | Native 内存 + 本地磁盘 |
| 状态规模 | 受堆内存限制，易 GC/OOM | 亿级 key 也能扛 |
| checkpoint 方式 | 全量快照写 HDFS | 增量 SST / changelog 上传 |
| 适用场景 | 中小状态量 | 大状态量生产首选 |

切换只需要一个配置：

```properties
spark.sql.streaming.stateStore.providerClass=org.apache.spark.sql.execution.streaming.state.RocksDBStateStoreProvider
spark.sql.streaming.stateStore.rocksdb.changelogCheckpointing.enabled=true
```

如果业务的状态规模可能增长到千万 key 以上，建议立项之初就直接上 RocksDB provider，后迁移的成本比想象高。

## 八、与 DStream 的对比及选型建议

| 维度 | Spark Streaming（DStream） | Structured Streaming |
|---|---|---|
| 抽象 | RDD 的时间序列 | 无限追加的表（DataFrame） |
| API | DStream 专属 API | SQL / DataFrame / Dataset，流批一套 |
| 优化器 | 无 Catalyst/Tungsten 加持 | 全量享受 |
| 事件时间 | 支持很弱 | 一等公民 + watermark |
| 一致性语义 | 至少一次，Exactly-Once 靠业务 | 端到端 Exactly-Once（引擎保证） |
| 延迟 | 秒级微批 | 微批秒级，连续模式毫秒级（实验） |
| 现状 | 维护态 | 官方主推，持续演进 |

结论很直接：**新项目没有理由再选 DStream**。除非你在维护一套老的 DStream 系统且稳定运行多年，否则一律上 Structured Streaming；对毫秒级延迟有硬性要求的场景（如风控实时决策），再去评估 Flink 这类纯流引擎。

## 九、总结

- Structured Streaming 的本质：**把流看作无限追加的表**，批查询的写法、流式的执行，流批一体由此而来；
- 模型三要素：Input Table、Query、Result Table；输出三模式：Complete / Append / Update，选错会在启动期被拦下；
- 事件时间是一等公民，`withWatermark` 一句话解决迟到数据与状态膨胀；
- 端到端 Exactly-Once = 可重放 Source + checkpoint/WAL + 幂等 Sink，三者缺一不可；
- 大状态量场景直接上 RocksDB StateStore provider；
- 新项目选型：Structured Streaming 优先，DStream 只用于存量维护。

---

摘要：Structured Streaming 是 Spark 2.x 之后官方主推的流计算引擎，它把"流"抽象成一张无限追加的表，让你用写批处理 SQL 的方式写实时任务，还顺带解决了事件时间、迟到数据和端到端 Exactly-Once 这三座大山。本文从编程模型、输出模式、水位线、状态管理和容错语义五个维度把它的核心设计讲透，最后给出与 DStream 的对比和选型建议。

Structured Streaming 结构化流概述：把流数据当作一张无限增长的表

大数据

后端

架构设计

Structured Streaming以“无限表”模型统一流批处理，支持SQL与DataFrame API，通过Watermark、StateStore及Checkpoint机制实现事件时间处理与端到端Exactly-Once语义。本文深入解析其编程模型、三种输出模式、状态管理及容错设计，并对比DStream，为实时计算选型提供权威参考。

代码解释

Kafka

Spark 

Hive

HDFS

让每一个 Agent，都跑在云上

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Structured Streaming以“无限表”模型统一流批处理，支持SQL与DataFrame API，通过Watermark、StateStore及Checkpoint机制实现事件时间处理与端到端Exactly-Once语义。本文深入解析其编程模型、三种输出模式、状态管理及容错设计，并对比DStream，为实时...

Structured Streaming 结构化流概述：把流数据当作一张无限增长的表-腾讯云开发者社区-腾讯云

Structured Streaming 结构化流概述：把流数据当作一张无限增长的表

Structured Streaming 结构化流概述：把流数据当作一张无限增长的表

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐