消息队列 / 系统课时
设计 Offset 提交边界
设计 Offset 提交边界
Offset 提交不是“消费到哪里”的记录,而是故障恢复时从哪里继续的承诺。本课把提交点放到业务处理完成之后,并用分区级下一条 Offset 表示恢复位置,从而在自动提交、手动提交和异常恢复之间建立可验证的边界。
学习目标
- 区分消费位置与已提交 Offset,正确理解“提交下一条待处理消息”的语义。
- 判断自动提交与手动提交各自会放大哪类恢复风险。
- 按业务处理完成点设计分区级提交边界,避免消息丢失或无谓重放。
先把 Offset 当作恢复游标
同一分区内,Consumer 有两个容易混淆的位置:当前消费位置会随着 poll() 返回记录而推进;已提交 Offset 则保存在消费组状态中,进程重启或 Rebalance 后会用它恢复。已提交值应该指向下一条尚未处理的记录。
例如分区 0 已可靠处理 Offset 40、41、42,正确提交值是 43,而不是 42。若此时进程宕机,新 Consumer 从 43 继续;如果只提交到 41,则 41、42 可能再次被读取。

自动提交不能代表业务完成
开启 enable.auto.commit 后,客户端会周期性提交消费进度,auto.commit.interval.ms 控制提交频率。这个机制只知道 Consumer 的拉取进度,不知道数据库写入、HTTP 调用、文件落盘或异步任务是否真正完成,因此不能把“自动提交成功”等同于“业务处理成功”。
enable.auto.commit=true
auto.commit.interval.ms=5000这段配置的生效行为是:客户端按周期在后台提交 Offset。验证时应同时观察业务处理日志与消费组已提交位置;如果应用把 poll() 返回的记录交给异步线程后立即继续拉取,已提交位置可能领先于真正完成的业务处理点。
手动提交放在处理完成之后
需要把 Kafka Offset 与业务完成点对齐时,先关闭自动提交,再在处理成功后提交每个分区的下一条 Offset。下面示例基于 Kafka Java Consumer 4.x API;把 <BOOTSTRAP_SERVERS> 和 <TOPIC> 替换成实际值后即可运行。
import java.time.Duration;
import java.util.Collections;
import java.util.List;
import java.util.Properties;
import org.apache.kafka.clients.consumer.ConsumerConfig;
import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.apache.kafka.clients.consumer.ConsumerRecords;
import org.apache.kafka.clients.consumer.KafkaConsumer;
import org.apache.kafka.clients.consumer.OffsetAndMetadata;
import org.apache.kafka.common.TopicPartition;
import org.apache.kafka.common.serialization.StringDeserializer;
public class ManualCommitBoundary {
public static void main(String[] args) {
Properties props = new Properties();
props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "<BOOTSTRAP_SERVERS>");
props.put(ConsumerConfig.GROUP_ID_CONFIG, "offset-boundary-demo");
props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "false");
props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
try (KafkaConsumer<String, String> consumer = new KafkaConsumer<>(props)) {
consumer.subscribe(List.of("<TOPIC>"));
while (true) {
ConsumerRecords<String, String> records = consumer.poll(Duration.ofSeconds(1));
for (TopicPartition partition : records.partitions()) {
for (ConsumerRecord<String, String> record : records.records(partition)) {
process(record);
}
// 只有该分区本批记录全部处理成功,才提交下一条待处理位置。
OffsetAndMetadata next = records.nextOffsets().get(partition);
consumer.commitSync(Collections.singletonMap(partition, next));
System.out.printf("committed %s -> %d%n", partition, next.offset());
}
}
}
}
private static void process(ConsumerRecord<String, String> record) {
System.out.printf("handled %s-%d@%d value=%s%n",
record.topic(), record.partition(), record.offset(), record.value());
}
}预期输出
handled <TOPIC>-<PARTITION>@<OFFSET> value=<VALUE>
committed <TOPIC>-<PARTITION> -> <NEXT_OFFSET>实际分区、Offset 和消息内容会不同。若 process() 在某条记录上抛出异常,本例不会执行该分区本批次的 commitSync();重启后最多重放尚未提交的已处理记录,而不会越过失败记录。
用故障后果检查边界
提交过早的典型路径是“先提交,再写数据库”。如果数据库写入前进程崩溃,恢复会从更大的 Offset 开始,未完成的记录可能被跳过。提交过晚则相反:业务已经成功,但 Offset 还没落下,故障后会再次处理,主要风险是重复副作用。
因此,数据库写入、扣款、发通知这类不可重复副作用还需要幂等键、去重表或业务事务配合。Kafka 的 Offset 提交只能决定从哪里恢复,不能自动把任意外部系统操作与 Offset 变成一个原子事务。
当处理被并发化时,提交边界必须按分区维护“连续完成”的最大位置。即使 Offset 45 已完成,只要 44 仍在执行,就不能提交 46;否则 44 失败后恢复点已经越过它。真正可靠的边界不是“最大已完成 Offset”,而是“所有更小 Offset 都已完成后的下一位”。