real-time-streaming

实时数据流处理实践指南

Real-Time Streaming 是一份面向实践者的实时数据管道构建与运维指南。该技能覆盖完整的流处理技术栈：从数据摄取（Kafka 生产者、基于 Debezium 的 CDC），到数据处理（Kafka Streams、Apache Flink），再到数据落地（sink、物化视图、事件溯源存储）。其重点在于生产级模式：精确一次语义（exactly-once semantics）、背压处理、状态管理与故障恢复。该技能面向已理解分布式系统基础、需要构建可大规模可靠运行的流式管道的工程师。

何时使用

当用户执行以下任务时触发此技能：设置或配置 Kafka 主题、生产者或消费者；编写 Flink 作业（DataStream 或 Table API、窗口、状态）；实现从数据库到流式管道的变更数据捕获（CDC）；设计流处理拓扑（连接、聚合、开窗）；调试消费者延迟、再均衡风暴或背压问题；实现精确一次或至少一次投递保证；使用流式基础设施构建事件溯源系统；在 Kafka Streams、Flink 或 Spark Streaming 之间做选择。

不适用于：通用的事件驱动架构决策（应使用 event-driven-architecture 技能）；不含实时组件的批处理 ETL 管道（应使用 data-engineering 技能）。

核心原则

将流视为事实来源——在流式架构中，日志（Kafka 主题）是权威记录，数据库、缓存与搜索索引都是派生视图，应从流向外设计，而非从数据库向外设计。

为并行而分区，为正确性而设键——分区决定最大并行度，键的选择决定顺序保证；应根据最高吞吐的访问模式选择分区键，必须按顺序处理的事件必须共享同一键（因而同一分区）。

精确一次是系统属性而非组件属性——没有任何单一组件能独立提供精确一次，它需要幂等生产者、事务写入与消费者偏移管理端到端协同工作，需理解保证在何处失效。

背压是特性而非缺陷——当消费者跟不上生产者时，系统必须发出信号；应显式处理背压而不是无界缓冲。Flink 原生处理，Kafka 消费者则需谨慎调优 max.poll.records 与 max.poll.interval.ms。

迟到数据不可避免——真实事件会乱序到达，应使用 watermark 定义“多晚算太晚”、用 allowed lateness 窗口处理滞后数据、用 side output 处理窗口关闭后到达的事件。

核心概念

流处理栈分为三层：传输层（Kafka、Pulsar、Kinesis）提供持久、有序、分区的日志；处理层（Flink、Kafka Streams、Spark Structured Streaming）从传输层读取、应用转换并写出结果；物化层（数据库、搜索索引、缓存）向应用提供处理后的数据。

Kafka 的核心模型围绕划分为分区的主题：生产者按键哈希或轮询写入分区；消费者组并行读取分区，每个分区只分配给组内一个消费者；偏移量跟踪进度；消费者组再均衡在消费者加入或离开时重新分配分区。

Flink 的执行模型基于数据流图：作业是算子（source、转换、sink）组成的 DAG；Flink 通过检查点（定期将算子状态快照到持久存储）管理状态；失败时从最近检查点恢复并从源偏移重放，从而实现精确一次处理。

变更数据捕获（CDC）将数据库变更转为事件流：Debezium 读取数据库事务日志（Postgres 的 WAL、MySQL 的 binlog）并将变更事件发布到 Kafka；每个事件包含行的前/后快照，使下游消费者能重建完整变更历史。

常见任务

设置 Kafka 主题：根据目标吞吐量与消费者并行度选择分区数，生产环境副本因子至少为 3。示例命令使用 partitions 12、replication-factor 3、retention.ms=604800000、cleanup.policy=delete、min.insync.replicas=2。建议分区数从预期最大消费者数的 2 倍开始；之后可增加分区但不可减少；更改分区数会破坏已有数据的基于键的顺序保证。

编写幂等 Kafka 生产者（Java）：启用幂等生产以防止重试产生重复。示例配置启用 enable.idempotence=true、acks=all、retries=Integer.MAX_VALUE、max.in.flight.requests.per.connection=5。启用幂等后，broker 使用序列号对重试去重，需要 acks=all，并允许最多 5 个在途请求同时保持每分区顺序。

编写 Flink 窗口聚合：在滚动 1 分钟窗口内按键计数事件，并处理迟到数据。示例使用 forBoundedOutOfOrderness(Duration.ofSeconds(10)) 设置 watermark，keyBy 用户 ID，TumblingEventTimeWindows.of(Time.minutes(1))，allowedLateness(Time.minutes(5))，并通过 sideOutputLateData 输出迟到数据。将 forBoundedOutOfOrderness 设为最大预期事件延迟；窗口触发后在 allowedLateness 内到达的事件会触发重算，之后到达的进入 side output。

使用 Debezium 与 Kafka Connect 配置 CDC：部署 Debezium PostgreSQL 连接器以流式传输表变更。示例配置包含 connector.class 为 io.debezium.connector.postgresql.PostgresConnector、topic.prefix 为 cdc、table.include.list 为 public.orders,public.order_items、plugin.name 为 pgoutput、slot.name 为 debezium_orders、snapshot.mode 为 initial，并使用 ByLogicalTableRouter 转换路由主题。应始终显式设置 slot.name 以避免孤儿复制槽；首次部署用 snapshot.mode=initial 捕获已有数据，重新部署时切换为 snapshot.mode=no_data。

使用 Kafka 事务实现精确一次：用事务原子地写入多个主题并提交偏移。示例调用 initTransactions、beginTransaction、逐条处理并发送到 output-topic、sendOffsetsToTransaction、commitTransaction；捕获 ProducerFencedException 或 OutOfOrderSequenceException 时关闭生产者（致命，必须重启），捕获 KafkaException 时中止事务。事务性消费者必须设置 isolation.level=read_committed 以避免读取未提交记录，这会增加等于事务时长的延迟。

在 Kafka Streams 中构建流表连接：使用紧凑主题中的客户数据丰富订单流。示例通过 StreamsBuilder 从 orders 构建 KStream、从 customers 构建 KTable，使用 join 与 Joined.with 生成 EnrichedOrder 并写入 enriched-orders。KTable 由本地 RocksDB 状态存储支撑；需确保 customers 主题使用 cleanup.policy=compact 以始终保留每个键的最新值，并监控状态存储大小。

处理消费者延迟与再均衡：监控并调优消费者性能以防延迟累积。示例使用 kafka-consumer-groups.sh 查看每分区消费者延迟，并列关键调优参数：max.poll.records=500、max.poll.interval.ms=300000、session.timeout.ms=45000、heartbeat.interval.ms=15000（为会话超时的 1/3）。若处理时间超过 max.poll.interval.ms，消费者会被驱逐并触发再均衡；可减少 max.poll.records 或增大间隔，并使用协作粘性再均衡（partition.assignment.strategy=CooperativeStickyAssignor）以最小化再均衡干扰。

反模式与常见错误

用单一分区保证顺序：破坏并行度、造成瓶颈；应按实体键分区，只有同一实体的事件需要顺序。
流处理中的无界状态：内存增长直至 OOM，检查点大小爆炸；应对状态使用 TTL、窗口聚合或增量清理。
忽略消费者组再均衡：再均衡风暴导致重复处理和延迟飙升；应使用协作粘性分配器，调优会话/轮询超时。
无监控的 CDC 复制槽：孤儿槽导致 WAL 膨胀和数据库磁盘耗尽；应对槽延迟告警，保守设置 max_replication_slots。
紧密循环轮询 Kafka 且无退避：主题为空时浪费 CPU，造成不必要的 broker 负载；应使用 poll(Duration.ofMillis(100)) 或更长，并调优 fetch.min.bytes。
跳过模式演进：生产者侧变更会破坏消费者反序列化；应使用带兼容性检查的模式注册表（Avro/Protobuf）。
无幂等性的处理：至少一次投递导致重复副作用；应使 sink 幂等（upsert、去重键、条件写入）。

参考文件

针对具体流处理领域的详细模式与实现指南，可阅读 references/ 文件夹中的相关文件：references/kafka-operations.md（主题管理、broker 调优、监控、安全设置）、references/flink-patterns.md（检查点、保存点、状态后端、复杂事件处理）、references/cdc-debezium.md（连接器配置、模式演进、快照策略、MySQL/Postgres 细节）、references/stream-processing-patterns.md（开窗策略、连接类型、去重、watermark 调优）。仅当当前任务需要时才加载参考文件，因为它们较长且会消耗上下文。

技能介绍