kafkaconsumer.poll() 会抛出serializationexception、illegaloperationerror、notcoordinatorerror、unknownmemberiderror等系统级异常，需显式捕获而非仅catch exception；wakeupexception须re-raise，kafkatimeouterror属正常；空返回不报错但可能暴露配置问题；多数异常不应立即重试，应按类型采取跳过、等待或告警策略。
捕获 KafkaConsumer.poll() 抛出的异常类型
poll() 是 Kafka 消费者拉取消息的核心方法，但它不只返回消息，还会在底层连接、心跳、元数据刷新等环节抛出异常。常见且必须捕获的包括：SerializationException（反序列化失败）、IllegalOperationError（如消费者已关闭后调用）、NotCoordinatorError（协调器变更）、UnknownMemberIdError（组成员 ID 失效）。这些不是业务逻辑错误，而是客户端与集群交互的“系统级信号”，跳过会导致静默中断或重复消费。
关键点：不要只 try-catch Exception，要显式列出已知可恢复/需特殊处理的异常类型，否则会掩盖真正的问题（比如配置错导致的 UnknownMemberIdError）。
-
SerializationException：通常因 value 或 key 的value_deserializer/key_deserializer解析失败，比如传入空字节或非法 JSON；应检查消息是否为 tombstone（message.value is None）再解序列化 -
WakeupException：由consumer.wakeup()主动触发，用于优雅退出；必须在 catch 块中 re-raise 或主动 break，否则会卡住线程 -
KafkaTimeoutError：poll(timeout_ms=...)超时未返回任何消息，属于正常现象，无需告警，但要注意别把它和网络断连混淆
为什么不能只靠 try: for msg in consumer: ... 捕获异常
迭代器形式（for msg in consumer）内部封装了 poll() 调用，但异常发生时迭代器直接终止，且不暴露底层错误原因。一旦遇到 NotCoordinatorError 或 GroupAuthorizationFailedError，程序会静默退出循环，日志里只看到“停止消费”，却找不到触发点。
正确做法是放弃隐式迭代，改用显式 poll() + 循环控制：
while not shutdown_flag:
try:
msgs = consumer.poll(timeout_ms=1000)
for tp, messages in msgs.items():
for msg in messages:
process(msg)
# 手动提交（若关闭 auto_commit）
consumer.commit()
except (SerializationException, NotCoordinatorError, UnknownMemberIdError) as e:
log.error("poll 异常: %s", e)
time.sleep(1) # 避免忙等
except WakeupException:
break
poll() 返回空结果 ≠ 异常，但可能暗示配置问题
返回空 dict 是完全合法的，尤其在 auto_offset_reset='latest' 且 topic 还没新消息时。但如果持续数分钟为空，且确认生产端正常，大概率是以下配置之一出错：
-
bootstrap_servers地址不可达或解析为 IPv6（如localhost→::1），应强制用127.0.0.1 -
group_id为空或含非法字符（如空格、下划线开头），导致无法加入消费者组，Kafka 日志报UnknownMemberIdError -
session_timeout_ms设得太小（如6000），而实际处理耗时波动大，心跳发不出就被踢出组，后续 poll 永远为空
这类问题不会抛异常，但消费停滞。建议定期检查 consumer.metrics() 中的 heartbeat-rate 和 join-rate 指标，比单纯看日志更可靠。
异常后要不要重试 poll()？
绝大多数情况下——不要立即重试。Kafka 客户端本身已有指数退避重试逻辑（如元数据刷新失败），手动加 while 循环重试 poll() 可能放大问题：比如 NotCoordinatorError 出现时，协调器正在切换，立刻重试只会加重请求压力；SerializationException 是数据问题，重试同一消息毫无意义。
合理策略是：
- 对网络类异常（
NodeNotReadyError、ConnectionError）：等待 1–3 秒后继续下一轮 poll - 对序列化/权限类异常（
SerializationException、TopicAuthorizationFailedError）：记录完整消息头（topic/partition/offset）和错误，跳过该批次，避免阻塞 - 对组管理异常（
UnknownMemberIdError、RebalanceInProgressError）：通常几秒内自动恢复，无需干预；若持续超 30 秒，应检查group_id和 broker 状态
真正的难点不在捕获，而在区分哪些异常该停、哪些该跳、哪些该告警——这取决于你的数据语义和 SLA。比如金融流水消息的 SerializationException 必须进死信队列人工介入，而日志类消息可以直接丢弃。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
