消息队列 / 系统课时
构造订单事件 EOS 场景
构造订单事件 EOS 场景
这节课把 Exactly-Once 落到一个可演练的订单事件链路:消费订单输入,完成一次处理,再向多个 Kafka 主题输出,并把消费位点与输出写入放进同一事务中。重点是划清 Kafka 事务覆盖的资源边界,形成可验证的“全有或全无”结果。
学习目标
- 能构造一个包含输入、处理、双主题输出和事务内 offset 提交的订单事件场景
- 能明确 Kafka 事务覆盖哪些读写,以及数据库、HTTP 等外部资源为什么不在同一原子边界内
- 能设计成功、abort 和重试三类故障的验收条件
先固定最小业务链路
假设消费者组从 orders.in 读取订单事件,完成订单状态计算后,同时写入 orders.out 和 orders.audit。一次处理的核心边界是:消费位点、业务结果和审计结果都交给同一个 Kafka 事务;事务提交成功才整体生效,事务中止则这次输出不作为已提交事务结果交付。

定义事件和两路输出
先用最小事件模型固定演练输入。一个订单事件只保留演练必需字段,避免把业务细节带进事务故障定位。
{
"orderId": "O-1001",
"eventType": "ORDER_CREATED",
"amount": 199.00,
"occurredAt": "<TIME>"
}预期结果
输入事件包含稳定的业务标识 orderId、事件类型、金额和事件时间,可作为一次处理的业务关联对象。处理完成后写入两个主题:orders.out 表示业务结果,orders.audit 表示审计结果。两路输出必须使用同一个事务;同时,输入记录对应的下一消费位点也必须通过 sendOffsetsToTransaction 纳入该事务,否则仍可能出现“输出已提交、输入位点未同步”的重复处理窗口。
用 Java Kafka 客户端固定事务边界
下面是一个完整的主示例:消费者从 orders.in 取一条或多条记录,Producer 开启事务,逐条处理后写入两个输出主题,再把本次处理记录对应的消费位点交给事务,最后提交。示例依赖 Kafka 客户端和可运行的 Kafka 集群;localhost:9092、Topic 与事务 ID 均可按实际环境调整。
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.clients.producer.KafkaProducer;
import org.apache.kafka.clients.producer.ProducerConfig;
import org.apache.kafka.clients.producer.ProducerRecord;
import org.apache.kafka.common.TopicPartition;
import org.apache.kafka.common.serialization.StringDeserializer;
import org.apache.kafka.common.serialization.StringSerializer;
import java.time.Duration;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.Properties;
public class OrderEosDemo {
private static final String INPUT_TOPIC = "orders.in";
private static final String OUTPUT_TOPIC = "orders.out";
private static final String AUDIT_TOPIC = "orders.audit";
private static final String GROUP_ID = "order-eos-demo";
public static void main(String[] args) {
Properties consumerProps = new Properties();
consumerProps.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
consumerProps.put(ConsumerConfig.GROUP_ID_CONFIG, GROUP_ID);
consumerProps.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
consumerProps.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
consumerProps.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "false");
consumerProps.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
Properties producerProps = new Properties();
producerProps.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
producerProps.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
producerProps.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
producerProps.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, "true");
producerProps.put(ProducerConfig.TRANSACTIONAL_ID_CONFIG, "order-eos-demo-<ID>");
try (KafkaConsumer<String, String> consumer = new KafkaConsumer<>(consumerProps);
KafkaProducer<String, String> producer = new KafkaProducer<>(producerProps)) {
consumer.subscribe(Collections.singletonList(INPUT_TOPIC));
producer.initTransactions();
ConsumerRecords<String, String> records = consumer.poll(Duration.ofSeconds(5));
if (records.isEmpty()) {
System.out.println("NO_INPUT_RECORD");
return;
}
for (ConsumerRecord<String, String> record : records) {
producer.beginTransaction();
try {
String orderId = record.key();
String event = record.value();
// 两路输出和当前输入记录的下一 offset 必须落在同一个 Kafka 事务中。
producer.send(new ProducerRecord<>(OUTPUT_TOPIC, orderId, event)).get();
producer.send(new ProducerRecord<>(AUDIT_TOPIC, orderId, "AUDIT:" + event)).get();
Map<TopicPartition, OffsetAndMetadata> offsets = new HashMap<>();
offsets.put(
new TopicPartition(record.topic(), record.partition()),
new OffsetAndMetadata(record.offset() + 1)
);
producer.sendOffsetsToTransaction(offsets, consumer.groupMetadata());
producer.commitTransaction();
} catch (Exception e) {
producer.abortTransaction();
throw e;
}
}
System.out.println("EOS_COMMITTED");
} catch (Exception e) {
System.err.println("EOS_ABORTED: " + e.getClass().getSimpleName());
throw new RuntimeException(e);
}
}
}预期结果
EOS_COMMITTED正常执行时,输入记录会先被消费者读取;随后同一条记录生成 orders.out 和 orders.audit 两条输出,并通过 sendOffsetsToTransaction 把该记录的下一消费位点纳入同一个事务。只有 commitTransaction() 成功后,这三部分才作为一次提交结果生效;任一步骤抛异常都会进入 abortTransaction(),本次事务中的输出不会作为已提交事务结果交给 read_committed 消费者。
示例使用 Kafka 客户端提供的 TopicPartition,不要为它自定义包装类型。sendOffsetsToTransaction 的 offset 必须表示“下一条待消费位置”,因此示例使用 record.offset() + 1;实际多分区批量处理时,应按分区整理本批次已经成功处理的最新 offset 再提交。
把 EOS 边界写进演练验收
演练至少准备三种结果。正常路径要求 orders.out、orders.audit 和消费位点一起前进;事务中途故障要求两路输出不作为已提交事务结果出现,同时输入位点不能单独提交;重试后要求最终成功处理只形成一次已提交的事务结果。
不要把数据库写入或远程 HTTP 调用直接算进 Kafka 事务。它们不受 Kafka 事务的原子提交保护,需要独立的一致性设计,例如事务型数据库配合 Outbox,或业务级幂等与补偿。这样演练时才能准确区分:问题发生在 Kafka 事务内部,还是发生在 Kafka 与外部资源之间的边界。
最后,把 orderId 作为输入和两路输出的关联键,再配合成功、abort、重试三类故障注入,就能得到一个足够小、又能真实验证“输出 + 消费位点”原子提交关系的订单事件 EOS 场景。