2. Kafka 核心概念回顾：Topic、Partition、Producer、Consumer、Broker、Offset 在 Go 中的映射
在深入 Go 与 Kafka 的流处理边界设计之前，必须建立精确的概念映射。Kafka 的六大核心概念——Topic、Partition、Producer、Consumer、Broker、Offset——在 Go 生态中并非直接以原始形态出现，而是通过 sarama、confluent-kafka-go 等客户端库进行了面向对象的封装。理解这种映射关系，是后续设计状态存储与流处理拓扑的基础。
核心原则：Kafka 是一个分布式日志（Log），而非传统消息队列。Go 中的映射必须体现“分区有序、全局追加”的日志语义，而非 AMQP 式的路由语义。
2.1 概念全景与 Go 类型映射
下表列出了 Kafka 原生概念与 Go 客户端库（以 sarama 为例）中的核心类型对应关系。这是后续所有代码讨论的词汇表。
| Kafka 原生概念 | Go 类型（sarama） | 核心职责 | Go 中关键字段/方法 |
|---|---|---|---|
| Broker | *sarama.Broker |
物理节点连接管理 | Addr, ID, Connected(), Open() |
| Topic | string (名称) + *sarama.TopicMetadata |
逻辑分类标识 | Name, Partitions (分区元数据数组) |
| Partition | int32 (分区 ID) + *sarama.PartitionMetadata |
物理日志分片 | ID, Leader, Replicas, Isr |
| Offset | int64 |
分区内消息序号 | sarama.OffsetNewest (-1), sarama.OffsetOldest (-2) |
| Producer | sarama.AsyncProducer / sarama.SyncProducer |
消息发布 | Input(), Successes(), Errors(), SendMessage() |
| Consumer | sarama.Consumer / sarama.ConsumerGroup |
消息拉取与组协调 | ConsumePartition(), Partitions(), Consume() |
| Consumer Group | sarama.ConsumerGroup + sarama.ConsumerGroupHandler |
分区再均衡与消费进度 | Setup(), Cleanup(), ConsumeClaim() |
| Record | *sarama.ProducerMessage / *sarama.ConsumerMessage |
消息载体 | Topic, Partition, Offset, Key, Value, Timestamp |
工程提示：在 Go 中，
Offset 被映射为 int64，但特殊常量 sarama.OffsetNewest 和 sarama.OffsetOldest 是负数，用于指定消费起始位置。这是 Go 映射中一个容易出错的细节——切勿将 -1 或 -2 作为实际偏移量存储。
2.2 分区模型与 Go 中的 Leader/Follower 映射
Kafka 的分区模型在 Go 中通过 PartitionMetadata 暴露。每个分区有一个 Leader Broker 和一组 Follower（ISR 集合）。Go 客户端在生产和消费时，必须感知 Leader 角色。
常见误区：Go 的
sarama.Consumer 在消费时，会自动通过 Metadata 请求找到分区 Leader。但如果你手动构造 sarama.ConsumerMessage 或使用低级别 API，必须确保连接的是 Leader Broker，否则会收到 ErrNotLeaderForPartition 错误。
2.3 Offset 在 Go 中的三种语义
Offset 在 Go 中并非单一概念，而是存在三种截然不同的语义。混淆它们会导致数据丢失或重复消费。
| Offset 语义 | Go 表示 | 存储位置 | 生命周期 | 典型用途 |
|---|---|---|---|---|
| 日志偏移量 | int64 (消息元数据) |
Kafka 日志段文件 | 持久化，不可变 | 消息唯一序号，用于精确一次语义 |
| 消费位置 | int64 (Consumer 内部) |
Consumer 内存 + __consumer_offsets | 可提交，可重置 | 记录当前消费进度 |
| 存储边界 | int64 (状态存储) |
外部状态存储 (如 RocksDB, Redis) | 与应用状态绑定 | 流处理中的 exactly-once 边界 |
Go 工程实践：在流处理场景中，永远不要将 Kafka 的日志 Offset 直接作为状态存储的版本号。日志 Offset 是分区内单调递增的，但状态存储需要的是全局或业务级别的版本。正确的做法是：将 Offset 作为“水位线”存储在外部，用于故障恢复时的重放边界。
2.4 Consumer Group 与 Go 的再均衡处理
Consumer Group 是 Go 中实现水平扩展的核心机制。sarama 的 ConsumerGroupHandler 接口定义了三个生命周期方法，直接映射到 Kafka 的再均衡协议。
// Go 中的 ConsumerGroupHandler 接口
type ConsumerGroupHandler interface {
// 再均衡开始前调用，通常用于提交偏移量或释放资源
Setup(session ConsumerGroupSession) error
// 再均衡完成后调用，用于清理临时状态
Cleanup(session ConsumerGroupSession) error
// 实际消费逻辑，在 Goroutine 中并发执行
ConsumeClaim(session ConsumerGroupSession, claim ConsumerGroupClaim) error
}再均衡发生时，Go 客户端的处理顺序如下：
- 撤销阶段：Kafka Coordinator 发送
LeaveGroup请求，sarama 调用所有活跃 Consumer 的Cleanup()。 - 分配阶段：Coordinator 使用分配策略（Range/RoundRobin/Sticky）重新分配分区。
- 初始化阶段：每个 Consumer 收到新分区列表，sarama 调用
Setup()。 - 消费阶段：为每个分配的分区启动一个 Goroutine，调用
ConsumeClaim()。
2.5 Go 中的消息路由：Key 与 Partition 映射
Producer 在 Go 中通过 Partitioner 接口决定消息写入哪个分区。这是 Kafka 流处理中“状态局部性”的基础。
// sarama 内置分区器
type Partitioner interface {
Partition(message *ProducerMessage, numPartitions int32) (int32, error)
RequiresConsistency() bool
}
// 常用分区策略
// 1. HashPartitioner: 对 Key 哈希取模，相同 Key 进入同一分区
// 2. RandomPartitioner: 随机分配，用于无 Key 消息
// 3. RoundRobinPartitioner: 轮询分配，负载均衡
状态存储边界设计启示：在流处理中，必须使用 HashPartitioner 确保相同业务 Key（如用户 ID、订单 ID）的消息始终进入同一分区。这是后续实现“分区内状态存储”的前提——只有同一分区的消息才能安全地共享本地状态，无需跨分区协调。
2.6 概念映射总结
Go 与 Kafka 的概念映射并非简单的 1:1 翻译，而是存在以下关键差异点：
- Broker 是连接对象，而非节点：Go 中的
*sarama.Broker是一个 TCP 连接句柄，一个物理 Broker 节点可能对应多个连接实例。 - Offset 是 int64，但语义多重：日志 Offset、消费 Offset、存储 Offset 在 Go 中都是
int64，必须通过上下文区分。 - Consumer Group 是接口，而非对象：Go 通过
ConsumerGroupHandler接口实现再均衡回调，这是与 Java 客户端最大的设计差异。 - Partition 是 int32，但元数据丰富：分区 ID 只是
int32，但PartitionMetadata包含了 Leader、Replicas、ISR 等完整拓扑信息。