消息队列 / 系统课时

封装可复用生产组件

封装可复用生产组件

可复用 Producer 组件的目标不是把 KafkaProducer 再包一层,而是统一消息信封、序列化、异步结果、异常分类和关闭语义,让业务代码只负责“发什么”,基础设施代码负责“怎么可靠地发”。本课实现一个边界清晰的 Java 生产模块。

学习目标

  • 设计稳定的消息信封,并把序列化职责收敛到生产组件
  • 用 CompletableFuture 统一成功回执与同步、异步发送异常
  • 建立可复用的异常分类和 flush、close 关闭流程

先固定组件边界

业务层应该传入 Topic、消息 Key 和业务载荷;生产组件负责生成 Kafka 记录、序列化信封、附加必要 Header、调用 send()、转换回调结果并在关闭时释放资源。这样 Topic 选择和业务语义仍然显式,而底层发送细节不会散落在每个服务里。

可复用 Kafka Producer 组件结构

统一信封至少要有业务事件 ID、事件类型、发生时间和载荷。追踪 ID 可以同时进入信封和 Kafka Header:信封便于下游持久化与重放,Header 便于链路基础设施读取而不解析正文。

实现统一发送模块

下面示例依赖 kafka-clients 与 jackson-databind,并假设 Kafka Broker 位于 localhost:9092。为了让序列化失败也进入同一套异常模型,组件先把信封转换成 byte[],再交给 Kafka 的 ByteArraySerializer。

java
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()
            );
        }
    }
}

预期输出

text
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,连接、元数据和批处理能力都会被反复重建,性能与可靠性都会变差。更合适的方式是在应用启动时创建一个长期实例,在整个服务生命周期内复用,并在优雅停机阶段统一关闭。

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

目录与阅读设置

阅读设置

17

记录一个想法

封装可复用生产组件

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

登录哪都通