别被“结构化”骗了：聊聊 Spark Structured Streaming 的原理与那些年我踩过的坑

说实话，第一次看到 Spark Structured Streaming 这个名字的时候，我是被“Structured”三个字骗进来的。

当年我天真地以为：

既然是结构化流处理，那不就是“写 SQL + 自动实时 + 永不翻车”吗？

结果呢？
上线第一天就翻车，延迟爆炸、数据重复、状态膨胀、Checkpoint 爆盘，运维同学半夜给我打电话那语气，我现在都记得。

所以今天这篇文章，不讲 PPT 里的“完美模型”，就聊三件事：

1. 它到底是怎么跑起来的
2. 它为什么“看起来简单，用起来要命”
3. 你该怎么避开那些新手必踩的坑

一、先说人话：Structured Streaming 到底是个啥？

一句话版本：

Structured Streaming = 把“流”伪装成一张“永远在增长的表”

你写的不是“流处理逻辑”，而是：

SELECT ...
FROM 表
GROUP BY ...

Spark 在背后偷偷帮你做了三件事：

1. 把数据切成 一个个 micro-batch
2. 每个 batch 都当成一次 普通 Spark SQL 任务
3. 把中间状态（State）悄悄存起来，下次接着算

也就是说——
Structured Streaming 本质上是“准实时的批处理”。

这一点你要是没想清楚，后面所有坑你都会踩。

二、一个最经典的 Structured Streaming 示例

咱直接上代码，感受一下它“看起来多简单”。

val df = spark.readStream
  .format("kafka")
  .option("kafka.bootstrap.servers", "localhost:9092")
  .option("subscribe", "events")
  .load()

val result = df
  .selectExpr("CAST(value AS STRING)")
  .groupBy("value")
  .count()

result.writeStream
  .outputMode("complete")
  .format("console")
  .start()

你看这代码：

• 没 watermark
• 没状态管理
• 没 offset 控制
• 没 checkpoint 策略

但它就是能跑。

这也是 Structured Streaming 最“坑”的地方：

👉 能跑 ≠ 能长期稳定跑

三、核心原理一句话总结（很重要）

如果你只能记住一句话，那就是这句：

Structured Streaming = Micro-Batch + State + Checkpoint

展开说：

1️⃣ Micro-Batch：不是你想的那种“流”

Spark 会按时间切批，比如：

• 每 1 秒一个 batch
• 每 5 秒一个 batch

batch 越小，延迟越低，但调度和 IO 压力越大

所以你看到的“低延迟”，其实是 Spark 在疯狂调度任务。

2️⃣ State：真正的“流处理地狱入口”

只要你写了：

• groupBy
• window
• distinct
• join

你就不可避免地引入了状态。

状态会：

• 存在 Executor 内存
• 定期落盘到 checkpoint
• 随着 key 数量线性增长

一句大实话：

90% 的 Structured Streaming 问题，最后都死在 State 上

3️⃣ Checkpoint：救命稻草，也是定时炸弹

Checkpoint 干嘛的？

• 保存 offset
• 保存 state
• 支持失败恢复

但问题是：

• checkpoint 在 HDFS / S3
• 小文件巨多
• State 大了之后，恢复慢到你怀疑人生

四、那些年我踩过的“经典大坑”

坑一：没 watermark，状态无限膨胀

这是新手 Top 1 翻车点。

df
  .groupBy(
    window(col("event_time"), "10 minutes"),
    col("user_id")
  )
  .count()

你以为它会“自动过期”？
不会。

没有 watermark = Spark 永远不敢丢状态。

正确姿势：

df
  .withWatermark("event_time", "30 minutes")
  .groupBy(
    window(col("event_time"), "10 minutes"),
    col("user_id")
  )
  .count()

我当年就因为少了这一行，
一个作业 3 天把 HDFS 打满。

坑二：outputMode 选错，延迟直接起飞

Structured Streaming 有三种输出模式：

• append
• update
• complete

新手最爱用 complete，因为“稳”。

但真相是：

complete = 每个 batch 全量输出

如果你的 state 有 1000 万条：

• 每个 batch 都要扫一遍
• 延迟直接指数级上升

一句建议：

能 append 就别 update，能 update 就别 complete

坑三：Kafka exactly-once 的幻觉

很多人以为：

“Structured Streaming + Kafka = Exactly Once”

不完全对。

• Source（Kafka）是 at-least-once
• Sink 是否 exactly-once，取决于你自己

比如写 MySQL：

result.writeStream
  .foreachBatch { (df, batchId) =>
    df.write.mode("append").jdbc(...)
  }

这里如果任务失败重试：

👉 batchId 会重放，数据会重复

解决方案？

• 幂等写
• 去重表
• 用 batchId 做事务控制

Spark 不会替你兜底业务一致性。

坑四：Join 流 = 双倍状态，双倍痛苦

streamA.join(streamB, "id")

听起来很美。

但实际上：

• A 有 state
• B 有 state
• join 后是 state × state

我见过最狠的一个 join 作业：

checkpoint 目录 1.2 TB

最后结局很统一：
作业下线，改架构。

五、我对 Structured Streaming 的真实看法

说点掏心窝子的。

Structured Streaming 不是银弹。

它非常适合：

• 指标聚合
• 实时统计
• 简单 ETL
• 数据补齐 + 延迟容忍

但它不适合：

• 超低延迟（<100ms）
• 高基数 state
• 复杂多流 join
• 强一致事务逻辑

一句话建议送给你：

把 Structured Streaming 当“流式批处理”，你会很快乐；
把它当“实时数据库”，你会很痛苦。

六、写在最后

这些年我越来越觉得：

技术的坑，不是文档里没有，而是没人告诉你“代价是什么”

Structured Streaming 的设计是优雅的，
但它的代价，全在 State 和 Checkpoint 里。

如果你正在用它，记住三句话：

1. 先想清楚状态会不会无限长
2. 先设计好失败后的幂等方案
3. 先算清 checkpoint 能不能扛住