摘要: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,而是同一套查询的两种执行方式------这就是所谓的"流批一体"。

二、核心模型:Input Table → Query → Result Table
整个模型只有三个概念,记住这三张表就抓住了主干:
- Input Table(输入表):数据源(Kafka、文件、Socket......)里每条到达的数据,都相当于往这张表里 INSERT 一行新记录。它是无界的、只增不减的。
- Query(查询) :你在输入表上定义的转换逻辑------
select、filter、groupBy、window,和静态 DataFrame 的写法一模一样。 - 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 里清掉。
这就回答了流计算里最难的两个问题:"窗口什么时候可以出结果"和"状态什么时候可以删",而且语义和引擎实现是绑定的,不用业务代码操心。

六、容错与端到端 Exactly-Once
Structured Streaming 的设计目标之一就是任意故障下的端到端精确一次语义,它靠三个组件配合实现:
- 可重放的 Source:每个流式 Source 都带 offset(Kafka offset、文件位点......),记录了"读到哪了",故障后可以重放;
- Checkpoint + WAL(预写日志):引擎把每个微批的 offset 范围和中间状态,先写进可靠存储(HDFS/OSS)里的 checkpoint 目录,再开始计算。Driver 挂了重启后,从 checkpoint 恢复到断点继续跑;
- 幂等的 Sink:重放意味着同一段数据可能被算两次,Sink 必须支持幂等写入(或者像 Delta Lake 那样支持事务),保证重复写不会产生脏数据。
三者齐备,端到端 Exactly-Once 才成立。实践中两个要点:
scala
// checkpoint 目录是流任务的"命根子",必须指向可靠存储
val query = df.writeStream
.option("checkpointLocation", "hdfs://namenode:8020/chk/wordcount")
.start()
- checkpoint 里存了查询的元信息和状态,改了代码逻辑(尤其是有状态算子)不能直接复用旧 checkpoint 重启,要么保证兼容性,要么换目录重新算。

七、状态管理: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 只用于存量维护。