Data Engineering Zoomcamp 实战:用 Python 构建 Kafka 流处理管道(JSON 与 Avro 序列化全解析)
Data Engineering Zoomcamp 实战:用 Python 构建 Kafka 流处理管道(JSON 与 Avro 序列化全解析)
本文以 Data Engineering Zoomcamp 课程仓库中的 07-streaming/extras/python 模块为核心,系统讲解如何利用 Python 生态(kafka-python、confluent-kafka、pyspark、faust)在 Docker 环境中搭建 Kafka 流处理管道。读完本文,你将掌握:用 docker-compose 一键拉起 Kafka、Schema Registry 与 Spark 集群;基于 kafka-python 实现 JSON 格式的生产者与消费者;基于 confluent-kafka 结合 Schema Registry 实现带 schema 的 Avro 序列化传输,并理解两类方案在配置、调用链与适用场景上的差异。
模块概览:一个文件夹,四条流处理技术路线
07-streaming/extras/python 是课程流处理(Stream-Processing with Python)章节的 Python 实战模块。原文档明确说明,该模块围绕四个 Python 库展开:kafka-python、confluent-kafka、pyspark 与 faust,并按功能拆分为若干独立子模块:
| 子模块 | 用途 | 涉及技术 |
|---|---|---|
| docker | 提供 Dockerfile 与 docker-compose 定义,在容器中运行 Kafka 和 Spark,是所有示例运行的前置条件 | Docker、Kafka、Spark |
| json_example | JSON 格式的生产者-消费者示例 | kafka-python |
| avro_example | Avro 格式的生产者-消费者示例(配合 Schema Registry) | confluent-kafka |
| streams-example | 流式处理进阶示例 | faust、pyspark(另有 redpanda 版本) |
| redpanda_example | 基于 Redpanda(Kafka 兼容)的简化示例 | kafka-python 兼容 API |
从依赖清单 requirements.txt 可以看到模块的完整技术栈:
kafka-python==1.4.6
confluent_kafka
requests
avro
faust
fastavro
其中 kafka-python==1.4.6 锁定版本以保证 API 行为一致;confluent_kafka 是 Confluent 官方的 Kafka 客户端(底层基于 librdkafka);avro 与 fastavro 用于 Avro 编码/解码;faust 则是基于 asyncio 的流处理框架。需要特别说明:运行任何生产者/消费者示例之前,必须先确保 Kafka 服务已启动,这也是 Docker 模块被列在最前面的原因。
前置环境:用 Docker 一键拉起 Kafka 与 Spark
原文档强调,Docker 模块是"运行后续模块的必要前置步骤"。进入 docker 目录后,按照 docker/README.md 中的四步流程操作即可完成环境搭建。
1. 构建 Spark 镜像
Spark 部分采用分层构建策略,docker/spark 目录下按层拆分了多个 Dockerfile:cluster-base.Dockerfile(基础镜像)、spark-base.Dockerfile(Spark 运行时)、spark-master.Dockerfile(Master 节点)、spark-worker.Dockerfile(Worker 节点)以及 jupyterlab.Dockerfile(交互式 Notebook 界面)。
2. 创建 Docker 网络与共享卷
Kafka 与 Spark 两组服务需要处于同一网络并共享工作目录,命令如下:
# 创建网络
docker network create kafka-spark-network
# 创建共享卷(Spark 各节点共享的 HDFS 工作区)
docker volume create --name=hadoop-distributed-file-system
这个共享卷与 docker-compose.yml 中声明的卷 shared-workspace 一一对应,保证 Spark 的 Master 与 Worker 节点能访问同一份数据。
3. 启动与停止服务
# 在 docker 目录(含 kafka 与 spark 子目录)启动全部服务
docker compose up -d
# 停止全部服务
docker compose down
4. 常用清理命令
# 删除所有容器
docker rm -f $(docker ps -a -q)
# 删除所有卷
docker volume rm $(docker volume ls -q)
注意:
docker compose up -d会依据 docker/docker-compose.yml 一次性拉起两组服务(文件里同时定义了 Spark 集群与 Kafka 全家桶)。
docker-compose.yml 中的服务拓扑
从 docker-compose.yml 的源码结构看,整套环境包含 8 个服务,端口映射与职责如下:
| 服务 | 镜像 | 端口 | 职责 |
|---|---|---|---|
zookeeper |
confluentinc/cp-zookeeper:7.2.0 |
2181 | Kafka 元数据协调(ZOOKEEPER_CLIENT_PORT: 2181) |
broker |
confluentinc/cp-kafka:7.2.0 |
9092 | Kafka Broker(外部客户端入口) |
schema-registry |
confluentinc/cp-schema-registry:7.2.0 |
8081 | Avro Schema 注册与校验 |
control-center |
confluentinc/cp-enterprise-control-center:7.2.0 |
9021 | Confluent 控制台,可视化管理 Topic 与消费组 |
jupyterlab |
jupyterlab(本地构建) |
8888 | Notebook 交互环境 |
spark-master |
spark-master(本地构建) |
8080 / 7077 | Spark Master(Web UI + 调度端口) |
spark-worker-1 |
spark-worker(本地构建) |
8083→8081 | Worker,SPARK_WORKER_CORES=1、SPARK_WORKER_MEMORY=4g |
spark-worker-2 |
spark-worker(本地构建) |
8082→8081 | Worker,配置同上 |
Kafka 双监听器配置(关键细节)
broker 服务的监听器配置值得重点关注,它是"容器内互通 + 宿主机访问"能够同时成立的关键:
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: LISTENER_BOB:PLAINTEXT,LISTENER_FRED:PLAINTEXT
KAFKA_LISTENERS: LISTENER_BOB://broker:29092,LISTENER_FRED://broker:9092
KAFKA_ADVERTISED_LISTENERS: LISTENER_BOB://broker:29092,LISTENER_FRED://localhost:9092
KAFKA_INTER_BROKER_LISTENER_NAME: LISTENER_BOB
LISTENER_BOB(broker:29092)用于容器内部通信:Broker 之间、Schema Registry 与 Control Center 都通过broker:29092访问(如SCHEMA_REGISTRY_KAFKASTORE_BOOTSTRAP_SERVERS: "broker:29092");LISTENER_FRED(localhost:9092)用于宿主机客户端:本机运行 Python 生产者/消费者时使用localhost:9092作为bootstrap.servers。
这与示例中 json_example/settings.py 的 BOOTSTRAP_SERVERS = <a href="https://link.gitcode.com/i/f7b646e91475a6685bfda06cb8744a2d" target="_blank">'localhost:9092'] 以及 [avro_example/settings.py 的 BOOTSTRAP_SERVERS = 'localhost:9092' 完全对应——宿主机客户端无需进入容器即可收发消息。
JSON 生产者-消费者示例:基于 kafka-python
JSON 示例位于 json_example,使用 kafka-python 库,消息以 JSON 字符串在 Kafka 中传输。整个示例由 4 个文件构成:数据模型 ride.py、配置 settings.py、生产者 producer.py 与消费者 consumer.py。
数据模型 Ride:CSV 行到 Python 对象
Ride 类(ride.py)承担"CSV 原始行 → 结构化对象 → JSON"的桥梁作用,其字段对应纽约出租车行程数据(trip data)的 18 个列:
- 时间字段
tpep_pickup_datetime、tpep_dropoff_datetime用datetime.strptime(arr[1], "%Y-%m-%d %H:%M:%S")解析; - 数值字段区分类型:
passenger_count、rate_code_id、pu_location_id、do_location_id转int,金额类字段(fare_amount、tip_amount、total_amount等)用Decimal保留精度; - 提供
from_dict类方法,供消费者端将 JSON 字典还原为Ride对象。
生产者:序列化配置与发送逻辑
producer.py 的关键点有三处:
1. 序列化配置(必须与 KafkaProducer 的预期匹配)
config = {
'bootstrap_servers': BOOTSTRAP_SERVERS,
'key_serializer': lambda key: str(key).encode(),
'value_serializer': lambda x: json.dumps(x.__dict__, default=str).encode('utf-8')
}
key_serializer 把消息键(上客地点 ID pu_location_id)转为字节;value_serializer 通过 json.dumps(x.__dict__, default=str) 将 Ride 对象的属性字典序列化为 UTF-8 编码的 JSON 字节。default=str 保证 Decimal、datetime 等非 JSON 原生类型也能被安全转换。
2. 读取 CSV 并构造消息
read_records 用 csv.reader 跳过表头,逐行构造 Ride 对象存入列表。
3. 发送与超时处理
publish_rides 对每条记录调用 self.producer.send(topic=topic, key=ride.pu_location_id, value=ride),并通过 record.get().offset 打印写入的偏移量;同时捕获 KafkaTimeoutError 输出异常信息。以 pu_location_id 作为消息键,意味着同一上客地点的记录会进入同一分区,从而保证分区内有序。
消费者:轮询消费与反序列化
consumer.py 的配置与生产者的序列化配置一一对应:
config = {
'bootstrap_servers': BOOTSTRAP_SERVERS,
'auto_offset_reset': 'earliest',
'enable_auto_commit': True,
'key_deserializer': lambda key: int(key.decode('utf-8')),
'value_deserializer': lambda x: loads(x.decode('utf-8'), object_hook=lambda d: Ride.from_dict(d)),
'group_id': 'consumer.group.id.json-example.1',
}
auto_offset_reset: 'earliest':当消费组没有已提交偏移量时,从最早消息开始消费;enable_auto_commit: True:启用自动提交偏移量;key_deserializer将键还原为int(与生产端str(key).encode()互逆);value_deserializer使用json.loads配合object_hook将字典还原为Ride对象(与生产端json.dumps(x.__dict__)互逆);group_id定义了消费组,多个消费者共享同一group_id时会自动进行分区再平衡。
消费主循环使用 self.consumer.poll(1.0) 轮询(注释说明 SIGINT 无法在 poll 中被优雅处理,因此限制超时为 1 秒以便响应 KeyboardInterrupt),收到消息后打印 msg_val.key 与 msg_val.value,中断后调用 consumer.close() 释放连接。
运行方式
在 json_example 目录下分别启动两个终端:
# 启动生产者脚本
python3 producer.py
# 启动消费者脚本
python3 consumer.py
Avro 生产者-消费者示例:基于 confluent-kafka 与 Schema Registry
Avro 示例位于 avro_example,使用 confluent-kafka 库,并通过 Confluent Schema Registry 进行 Avro schema 的注册、校验与版本管理。相比 JSON 的"自由格式",Avro 方案为每条消息携带 schema,从根源上约束了生产端与消费端的数据契约。
核心配置:Schema Registry 与主题
settings.py 定义了关键参数:
RIDE_KEY_SCHEMA_PATH = '../resources/schemas/taxi_ride_key.avsc'
RIDE_VALUE_SCHEMA_PATH = '../resources/schemas/taxi_ride_value.avsc'
SCHEMA_REGISTRY_URL = 'http://localhost:8081'
BOOTSTRAP_SERVERS = 'localhost:9092'
KAFKA_TOPIC = 'rides_avro'
SCHEMA_REGISTRY_URL指向 docker-compose 中 schema-registry 服务的8081端口;- 消息键与消息值使用不同的 schema 文件(
taxi_ride_key.avsc与taxi_ride_value.avsc),分别对应键与值的序列化; - 主题为
rides_avro,与 JSON 示例的rides_json相互独立。
键/值模型与 Schema 转换函数
与 JSON 示例相比,Avro 示例将"键"和"值"拆成了两个模型(ride_record_key.py 与 ride_record.py):
RideRecordKey仅包含vendor_id(生产端按供应商 ID 分区);RideRecord包含 5 个字段:vendor_id、passenger_count、trip_distance、payment_type、total_amount,相比 JSON 版 18 字段更精简,是演示 Avro schema 演进的典型最小集。
两个模型各提供一对互逆函数,作为 Avro 序列化器与 Python 对象之间的转换钩子(Avro 序列化器按 schema 编码 dict,因此需要 xxx_to_dict 把对象转 dict;反序列化器需要 dict_to_xxx 把 dict 还原为对象):
def dict_to_ride_record(obj, ctx):
if obj is None:
return None
return RideRecord.from_dict(obj)
def ride_record_to_dict(ride_record: RideRecord, ctx):
return ride_record.__dict__
注意:从 producer.py 的 read_records 实现可以看出,生产端读取 CSV 时仅选取 row[0](vendor_id)、row[3](passenger_count)、row[4](trip_distance)、row[9](payment_type)、row[16](total_amount)五个列构建 RideRecord,并将 row[0] 作为键——这与值 schema 的字段定义严格对齐。
生产者:AvroSerializer + 回调确认
producer.py 的初始化流程展示了 Confluent 客户端的标准三段式配置:
schema_registry_props = {'url': props['schema_registry.url']}
schema_registry_client = SchemaRegistryClient(schema_registry_props)
self.key_serializer = AvroSerializer(schema_registry_client, key_schema_str, ride_record_key_to_dict)
self.value_serializer = AvroSerializer(schema_registry_client, value_schema_str, ride_record_to_dict)
producer_props = {'bootstrap.servers': props['bootstrap.servers']}
self.producer = Producer(producer_props)
- 用
SchemaRegistryClient连接 Schema Registry; - 分别用键 schema 与值 schema 构造
AvroSerializer(第三个参数是对象转 dict 的回调); - 用
bootstrap.servers构造底层基于 librdkafka 的Producer。
发送消息时使用 producer.produce(...)(异步、非阻塞),并注册 on_delivery=self.delivery_report 回调,在 delivery_report 中打印 msg.topic()、msg.partition()、msg.offset(),或输出投递失败错误。消息结束前调用 self.producer.flush() 等待所有待发送消息落盘,随后 sleep(1) 确保服务端处理完成——这是异步生产者"确认已发出"的关键一步。
消费者:AvroDeserializer + 轮询循环
consumer.py 与生产者对称:先用同一套 key/value schema 构造 AvroDeserializer(第三个参数是 dict 转对象的回调),再配置消费参数:
consumer_props = {'bootstrap.servers': props['bootstrap.servers'],
'group.id': 'datatalkclubs.taxirides.avro.consumer.2',
'auto.offset.reset': "earliest"}
消费循环通过 self.consumer.poll(1.0) 拉取消息(同样以 1 秒为超时以响应中断),并对 msg.key() 与 msg.value() 分别调用反序列化器——注意反序列化时必须传入 SerializationContext(msg.topic(), MessageField.KEY / MessageField.VALUE),告知 Schema Registry 该字节属于键还是值(同一主题的键与值可能使用不同 schema,字段语义不同):
key = self.avro_key_deserializer(msg.key(), SerializationContext(msg.topic(), MessageField.KEY))
record = self.avro_value_deserializer(msg.value(), SerializationContext(msg.topic(), MessageField.VALUE))
SerializationContext 与 MessageField 正是用于区分这两种场景,这也是 Avro 方案相比 JSON 方案多出的关键概念。
运行方式
与 JSON 示例一致,在 avro_example 目录下分别启动:
# 启动生产者脚本(需确保 schema-registry 服务已启动)
python3 producer.py
# 启动消费者脚本
python3 consumer.py
JSON 与 Avro 两种方案的对比
| 维度 | JSON 示例(kafka-python) |
Avro 示例(confluent-kafka) |
|---|---|---|
| 序列化方式 | json.dumps 手写序列化 |
Schema Registry + AvroSerializer/AvroDeserializer |
| 数据契约 | 无强制 schema,字段靠约定 | .avsc schema 强制约束,天然支持演进与校验 |
| 客户端底层 | 纯 Python 实现 | librdkafka(C 库)绑定,吞吐与功能更全 |
| 键/值处理 | 共用 Ride 模型,键为 pu_location_id |
键值分离模型,键为 vendor_id,各自独立 schema |
| 消息确认 | send().get() 同步等待 offset |
produce() 异步 + on_delivery 回调 + flush() |
| 依赖组件 | 仅需 Kafka Broker | 需 Kafka Broker + Schema Registry(8081) |
从 requirements.txt 可见,avro 与 fastavro 两个库同时存在:avro 提供 Avro 编解码核心能力,fastavro 以 Cython 加速实现,二者共同支撑 Schema Registry 客户端对 Avro 数据的处理。
进阶路线:faust 与 PySpark 流处理
原文档将模块定义为四条技术路线,除上述两个"生产者-消费者"示例外,streams-example 目录还提供了更高阶的流处理示例:
- streams-example/faust:基于
faust框架,将 Kafka 流视为可编程的数据流,示例覆盖流式统计(stream_count_vendor_trips.py)、价格分支(branch_price.py)、窗口聚合(windowing.py)等场景,配合producer_taxi_json.py与taxi_rides.py数据模型使用; - streams-example/pyspark:基于 PySpark Structured Streaming,通过 streaming.py 与 spark-submit.sh 提交流式作业,并配套
streaming-notebook.ipynb提供交互式演示,可直接跑在 Docker 环境中的 JupyterLab(8888 端口)上; - streams-example/redpanda 与 redpanda_example:提供不依赖 ZooKeeper 的 Redpanda 轻量替代方案,使用更少的服务即可完成相同演示。
这些目录与 json_example、avro_example 共享同一套 docker 环境:PySpark 流式作业运行于 docker-compose 启动的 Spark 集群(spark-master:7077、Worker 各分配 1 核 4G 内存),faust 应用则直接消费 Broker 上由 JSON 生产者写入的消息,形成完整的学习链路。
常见问题与排查要点
- 消费者收不到消息:优先检查
BOOTSTRAP_SERVERS是否指向localhost:9092(外部监听器 LISTENER_FRED),并确认auto.offset.reset配置;若消费组已存在历史偏移,可更换group_id或从 earliest 重新消费。 - Avro 示例报 schema 相关错误:确认
schema-registry服务已随 docker-compose 启动且SCHEMA_REGISTRY_URL为http://localhost:8081;键与值的反序列化必须分别传入MessageField.KEY与MessageField.VALUE。 - 跨容器访问失败:Broker 对外监听
LISTENER_FRED://localhost:9092仅映射宿主机;若在容器内访问,需改用内部监听器broker:29092。 - 生产者异步发送不落盘:
confluent_kafka.Producer.produce()是异步的,务必在退出前调用producer.flush(),否则消息可能未及发送进程即退出。
本文所涉及的示例均位于仓库 07-streaming/extras/python 目录下,完整源码(生产者、消费者、数据模型、docker-compose 与 Dockerfile)可直接对照阅读与运行。