消息队列 / 系统课时

配置 Exactly-Once Processing

配置 Exactly-Once Processing

本课解决一个最容易被误解的问题:Kafka Streams 中什么时候应该选择 at-least-once,什么时候应该选择 exactly-once 处理保证。你将看到 processing.guarantee 如何影响应用的提交语义,以及为什么 exactly_once_v2 不是“业务代码天然只执行一次”。

学习目标

  • 能正确配置 processing.guarantee
  • 能解释 at-least-once 与 exactly-once_v2 的核心差异
  • 能根据业务一致性要求判断是否值得采用 Exactly-Once

配置项决定处理保证

Kafka Streams 通过 processing.guarantee 指定处理保证级别。常见选择是 at_least_once 与 exactly_once_v2。前者强调至少一次处理,故障恢复时允许重复处理;后者通过 Kafka 事务协调输入 offset、输出记录以及相关状态提交,目标是避免下游观察到重复的已提交结果。

一个最小配置可以写成:

java
import java.util.Properties;
import org.apache.kafka.common.serialization.Serdes;
import org.apache.kafka.streams.KafkaStreams;
import org.apache.kafka.streams.StreamsBuilder;
import org.apache.kafka.streams.StreamsConfig;
import org.apache.kafka.streams.kstream.KStream;

public class ExactlyOnceConfigDemo {
    public static void main(String[] args) {
        Properties props = new Properties();
        props.put(StreamsConfig.APPLICATION_ID_CONFIG, "orders-eos-demo");
        props.put(StreamsConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:<PORT>");
        props.put(StreamsConfig.DEFAULT_KEY_SERDE_CLASS_CONFIG, Serdes.String().getClass());
        props.put(StreamsConfig.DEFAULT_VALUE_SERDE_CLASS_CONFIG, Serdes.String().getClass());
        props.put(StreamsConfig.PROCESSING_GUARANTEE_CONFIG, "exactly_once_v2");

        StreamsBuilder builder = new StreamsBuilder();
        KStream<String, String> orders = builder.stream("orders");
        orders.to("processed-orders");

        KafkaStreams streams = new KafkaStreams(builder.build(), props);
        streams.start();
    }
}

预期结果

text
Kafka Streams 应用启动后,以 exactly_once_v2 配置运行处理拓扑;实际日志内容和线程信息可能因 Kafka 环境不同而不同。

示例中的 <PORT> 是环境相关占位符,需要替换为实际 Kafka 监听端口。生产应用还应补充关闭钩子、错误处理、序列化配置等运行所需设置。

两种保证如何选择

at_least_once 的典型语义是:处理成功后推进消费进度,但在故障恢复等场景中,同一输入记录可能再次进入处理流程。它通常更简单、成本更低,适合业务本身具备幂等能力,或允许少量重复的场景。

exactly_once_v2 关注的是 Kafka Streams 处理链的原子提交。它更适合“输入被消费后产生的输出,必须与对应处理结果保持一致”的场景,例如金额汇总、状态同步和多阶段流式计算。

维度 at_least_once exactly_once_v2
重复处理容忍 需要业务侧考虑 Kafka Streams 提供更强的提交语义
配置复杂度 较低 较高
事务协调成本 较低 更高
适用场景 幂等业务、可接受重复 对结果重复敏感的一致性链路

不要把 Exactly-Once 理解成“整个业务系统只执行一次”。例如流处理调用外部 HTTP 服务、邮件系统或无法参与同一事务边界的数据库时,外部副作用仍然需要单独设计幂等、去重或补偿机制。

配置生效后的验证方式

配置完成后,至少验证应用能够正常启动、拓扑能够处理数据,并确认故障恢复后的结果符合预期。对于 EOS 场景,验证重点不是“日志里有没有消费两次”,而是检查下游最终可见的已提交结果是否保持一致。

可以先检查当前配置是否已经被应用读取。下面的代码用于在启动时打印关键配置:

java
System.out.println("processing.guarantee=" +
        props.getProperty(StreamsConfig.PROCESSING_GUARANTEE_CONFIG));

预期输出

text
processing.guarantee=exactly_once_v2

真正的验收还应覆盖故障恢复,例如让应用在处理过程中停止并重新启动,再核对输入记录对应的已提交输出和状态是否满足业务预期。单次正常运行成功,不能证明 Exactly-Once 已经得到验证。

什么时候不要只依赖 Exactly-Once

Exactly-Once 解决的是 Kafka Streams 处理边界内的一致性问题,不会自动解决数据库事务、远程调用、第三方 API 和人工操作带来的重复副作用。只要业务跨出了 Kafka Streams 自身能够协调的提交边界,就需要继续设计幂等键、去重记录、重试策略或补偿流程。

因此,配置决策应从“业务是否允许重复结果”出发,而不是看到 Exactly-Once 就默认开启。对纯 Kafka 流式处理且重复结果代价高的链路,exactly_once_v2 更有价值;对可幂等、对重复不敏感或对吞吐和资源开销更敏感的链路,at_least_once 可能更合适。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

配置 Exactly-Once Processing

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通