消息队列 / 系统课时
封装可复用生产组件
封装可复用生产组件
可复用 Producer 组件的目标不是把 KafkaProducer 再包一层,而是统一消息信封、序列化、异步结果、异常分类和关闭语义,让业务代码只负责“发什么”,基础设施代码负责“怎么可靠地发”。本课实现一个边界清晰的 Java 生产模块。
学习目标
- 设计稳定的消息信封,并把序列化职责收敛到生产组件
- 用
CompletableFuture统一成功回执与同步、异步发送异常 - 建立可复用的异常分类和
flush、close关闭流程
先固定组件边界
业务层应该传入 Topic、消息 Key 和业务载荷;生产组件负责生成 Kafka 记录、序列化信封、附加必要 Header、调用 send()、转换回调结果并在关闭时释放资源。这样 Topic 选择和业务语义仍然显式,而底层发送细节不会散落在每个服务里。

统一信封至少要有业务事件 ID、事件类型、发生时间和载荷。追踪 ID 可以同时进入信封和 Kafka Header:信封便于下游持久化与重放,Header 便于链路基础设施读取而不解析正文。
实现统一发送模块
下面示例依赖 kafka-clients 与 jackson-databind,并假设 Kafka Broker 位于 localhost:9092。为了让序列化失败也进入同一套异常模型,组件先把信封转换成 byte[],再交给 Kafka 的 ByteArraySerializer。
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.kafka.clients.producer.*;
import org.apache.kafka.common.errors.AuthorizationException;
import org.apache.kafka.common.errors.RetriableException;
import org.apache.kafka.common.errors.TimeoutException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Properties;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
public class ReusableProducerDemo {
record MessageEnvelope<T>(
String eventId,
String eventType,
long occurredAtEpochMs,
String traceId,
T payload
) {}
record SendResult(String topic, int partition, long offset) {}
enum FailureKind {
SERIALIZATION, TIMEOUT, AUTHORIZATION, RETRIABLE, FATAL
}
static final class ProducerSendException extends RuntimeException {
final FailureKind kind;
ProducerSendException(FailureKind kind, Throwable cause) {
super(kind + ": " + cause.getMessage(), cause);
this.kind = kind;
}
}
static final class ProducerComponent implements AutoCloseable {
private final KafkaProducer<String, byte[]> producer;
private final ObjectMapper mapper;
ProducerComponent(Properties props, ObjectMapper mapper) {
this.producer = new KafkaProducer<>(props);
this.mapper = mapper;
}
CompletableFuture<SendResult> send(
String topic,
String key,
MessageEnvelope<?> envelope
) {
final byte[] value;
try {
value = mapper.writeValueAsBytes(envelope);
} catch (JsonProcessingException e) {
return CompletableFuture.failedFuture(
new ProducerSendException(FailureKind.SERIALIZATION, e)
);
}
ProducerRecord<String, byte[]> record =
new ProducerRecord<>(topic, key, value);
record.headers().add(
"trace-id",
envelope.traceId().getBytes(StandardCharsets.UTF_8)
);
CompletableFuture<SendResult> future = new CompletableFuture<>();
try {
producer.send(record, (metadata, exception) -> {
if (exception == null) {
future.complete(new SendResult(
metadata.topic(),
metadata.partition(),
metadata.offset()
));
} else {
future.completeExceptionally(classify(exception));
}
});
} catch (RuntimeException e) {
future.completeExceptionally(classify(e));
}
return future;
}
private ProducerSendException classify(Throwable error) {
if (error instanceof TimeoutException) {
return new ProducerSendException(FailureKind.TIMEOUT, error);
}
if (error instanceof AuthorizationException) {
return new ProducerSendException(FailureKind.AUTHORIZATION, error);
}
if (error instanceof RetriableException) {
return new ProducerSendException(FailureKind.RETRIABLE, error);
}
return new ProducerSendException(FailureKind.FATAL, error);
}
@Override
public void close() {
producer.flush();
producer.close(Duration.ofSeconds(10));
}
}
public static void main(String[] args) throws Exception {
Properties props = new Properties();
props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG,
"org.apache.kafka.common.serialization.StringSerializer");
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG,
"org.apache.kafka.common.serialization.ByteArraySerializer");
props.put(ProducerConfig.ACKS_CONFIG, "all");
props.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, "true");
try (ProducerComponent producer =
new ProducerComponent(props, new ObjectMapper())) {
MessageEnvelope<String> envelope = new MessageEnvelope<>(
UUID.randomUUID().toString(),
"OrderCreated",
System.currentTimeMillis(),
UUID.randomUUID().toString(),
"order-1001"
);
SendResult result = producer
.send("orders.events", "order-1001", envelope)
.get();
System.out.printf(
"sent topic=%s partition=%d offset=%d%n",
result.topic(),
result.partition(),
result.offset()
);
}
}
}预期输出
sent topic=orders.events partition=<ID> offset=<ID><ID> 由实际 Topic 分区和当前日志位置决定。若序列化失败、权限不足或请求超时,CompletableFuture 会以 ProducerSendException 结束,业务层可以读取其中的 FailureKind 决定是否重试、告警或直接失败。
让异常分类真正可复用
异常分类的价值在于把 Kafka 具体异常与业务策略解耦。RETRIABLE 可以进入受控重试,AUTHORIZATION 通常需要修复权限而不是重试,SERIALIZATION 多半意味着消息结构或数据不合法,FATAL 则应保留原始异常并快速暴露。
组件同时捕获 send() 直接抛出的同步异常和回调中的异步异常,避免业务方必须理解两套失败路径。重试次数、退避和死信策略不要硬编码在这个薄封装里,应由上层按照事件重要性和幂等能力决定。
正确关闭而不是随进程退出
KafkaProducer 内部维护缓冲区和 I/O 线程,因此组件应拥有唯一生命周期。应用停止接收新请求后,再调用组件的 close();示例先 flush() 等待已提交记录完成,再给 close(Duration) 一个明确的退出窗口。
如果每发一条消息都创建和关闭一个 KafkaProducer,连接、元数据和批处理能力都会被反复重建,性能与可靠性都会变差。更合适的方式是在应用启动时创建一个长期实例,在整个服务生命周期内复用,并在优雅停机阶段统一关闭。