@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-kafka/SKILL.md

@@ -1,580 +1,56 @@
 ---
 name: avatar-boot-starter-kafka
-description: 当涉及 Kafka、消息队列、消息生产、消息消费、事件驱动 相关功能时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于 spring-kafka 的消息队列能力，包含生产者/消费者自动配置、JSON 序列化、死信队列、幂等消费。
+description: Avatar Boot Kafka 模块使用指南。当用户询问 Kafka 消息发送、消费者配置、事务消息、批量发送、消费者组、偏移量管理，或需要接入 avatar-boot-starter-kafka 时触发。
 ---
 
-Avatar Boot 的 Kafka 消息队列集成模块，基于 spring-kafka（版本由 Spring Boot BOM 管理）提供开箱即用的消息生产和消费能力。
+# Avatar Boot Starter Kafka 使用指南
 
-## 功能特性
+你是 Avatar Boot Kafka 模块的使用顾问与开发助手。
 
-- ✅ **自动配置** - 基于 Spring Boot 自动配置机制，自动装配 KafkaTemplate 和消费者
-- ✅ **JSON 序列化** - 内置 JSON 序列化/反序列化支持，无缝传输 Java 对象
-- ✅ **消费者组管理** - 支持消费者组和分区分配策略配置
-- ✅ **死信队列** - 内置 DLT（Dead Letter Topic）支持，处理消费失败的消息
-- ✅ **幂等消费** - 提供幂等消费模式，防止消息重复处理
-- ✅ **监控集成** - 集成 Micrometer 指标，监控生产者/消费者状态
+## 交互流程（必须遵守）
 
-## 快速开始
+**每次被触发时，先通过 AskUserQuestion 工具询问用户意图：**
 
-### 1. 添加依赖
+问题："您好！我是 Avatar Boot Kafka 模块助手，请问您需要哪方面的帮助？"
+选项：
+1. **快速接入** - 添加依赖、配置 Kafka 连接
+2. **发送消息** - 同步/异步/带Key/批量发送
+3. **消费消息** - 基础消费、批量消费、手动提交偏移量
+4. **事务消息** - 保证消息与数据库操作的一致性
+5. **最佳实践** - 幂等处理、Key 设计、异常处理
 
-在项目的 `pom.xml` 中添加依赖：
+**根据用户选择，用 Read 工具按下方「文档读取路由」加载对应文档，然后给出具体指导。**
 
-```xml
-<dependency>
-    <groupId>com.iflytek.avatar.boot</groupId>
-    <artifactId>avatar-boot-starter-kafka</artifactId>
-</dependency>
-```
-
-> 版本由 Avatar Boot BOM 统一管理，无需指定 version。spring-kafka 版本由 Spring Boot 3.5.3 父 BOM 管理。
-
-### 2. 配置文件
-
-在 `application.yml` 中添加 Kafka 配置：
-
-```yaml
-spring:
-  kafka:
-    bootstrap-servers: localhost:9092
-    producer:
-      retries: 3                              # 重试次数
-      batch-size: 16384                       # 批量发送大小（16KB）
-      buffer-memory: 33554432                 # 缓冲区大小（32MB）
-      acks: all                               # 确认机制：all 表示所有副本确认
-      key-serializer: org.apache.kafka.common.serialization.StringSerializer
-      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer
-      properties:
-        linger.ms: 10                         # 等待时间（毫秒），增大可提高吞吐量
-        max.request.size: 1048576             # 最大请求大小（1MB）
-        enable.idempotence: true              # 启用生产者幂等
-    consumer:
-      group-id: ${spring.application.name}-group
-      auto-offset-reset: earliest             # 无偏移量时从最早开始消费
-      enable-auto-commit: false               # 关闭自动提交（使用手动确认）
-      max-poll-records: 500                   # 每次拉取最大记录数
-      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
-      value-deserializer: org.springframework.kafka.support.serializer.JsonDeserializer
-      properties:
-        spring.json.trusted.packages: com.example.*  # 信任的反序列化包
-        session.timeout.ms: 30000
-        heartbeat.interval.ms: 10000
-        max.poll.interval.ms: 300000          # 最大处理时间（5分钟）
-    listener:
-      ack-mode: MANUAL_IMMEDIATE              # 手动确认模式
-      concurrency: 3                          # 消费者并发数
-```
-
-## 生产者（Producer）
-
-### 基本消息发送
-
-```java
-package com.example.producer;
-
-import com.example.event.OrderCreatedEvent;
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.kafka.core.KafkaTemplate;
-import org.springframework.kafka.support.SendResult;
-import org.springframework.stereotype.Service;
-
-import java.util.concurrent.CompletableFuture;
-
-@Slf4j
-@Service
-@RequiredArgsConstructor
-public class OrderEventProducer {
-
-    private final KafkaTemplate<String, Object> kafkaTemplate;
-
-    private static final String TOPIC = "order-events";
-
-    /**
-     * 异步发送消息（推荐）
-     */
-    public void sendOrderCreatedEvent(OrderCreatedEvent event) {
-        CompletableFuture<SendResult<String, Object>> future =
-                kafkaTemplate.send(TOPIC, event.getOrderNo(), event);
-
-        future.whenComplete((result, ex) -> {
-            if (ex == null) {
-                log.info("消息发送成功: topic={}, partition={}, offset={}",
-                        result.getRecordMetadata().topic(),
-                        result.getRecordMetadata().partition(),
-                        result.getRecordMetadata().offset());
-            } else {
-                log.error("消息发送失败: event={}", event, ex);
-                // 进行补偿处理：入库重试、告警等
-            }
-        });
-    }
-
-    /**
-     * 同步发送消息（需要等待结果）
-     */
-    public SendResult<String, Object> sendSync(String topic, String key, Object message) {
-        try {
-            return kafkaTemplate.send(topic, key, message).get();
-        } catch (Exception e) {
-            log.error("同步发送消息失败: topic={}, key={}", topic, key, e);
-            throw new RuntimeException("消息发送失败", e);
-        }
-    }
-
-    /**
-     * 发送到指定分区
-     */
-    public void sendToPartition(String topic, int partition, String key, Object message) {
-        kafkaTemplate.send(topic, partition, key, message);
-    }
-}
-```
-
-### 事件定义
-
-```java
-package com.example.event;
-
-import lombok.AllArgsConstructor;
-import lombok.Data;
-import lombok.NoArgsConstructor;
-
-import java.io.Serializable;
-import java.math.BigDecimal;
-import java.time.LocalDateTime;
-
-@Data
-@NoArgsConstructor
-@AllArgsConstructor
-public class OrderCreatedEvent implements Serializable {
-
-    private String orderNo;
-    private Long userId;
-    private BigDecimal totalAmount;
-    private LocalDateTime createTime;
-    private String eventId;  // 用于幂等去重
-}
-```
-
-## 消费者（Consumer）
-
-### 基本消费
-
-```java
-package com.example.consumer;
-
-import com.example.event.OrderCreatedEvent;
-import lombok.extern.slf4j.Slf4j;
-import org.apache.kafka.clients.consumer.ConsumerRecord;
-import org.springframework.kafka.annotation.KafkaListener;
-import org.springframework.kafka.support.Acknowledgment;
-import org.springframework.stereotype.Component;
-
-@Slf4j
-@Component
-public class OrderEventConsumer {
-
-    /**
-     * 单条消息消费（手动确认）
-     */
-    @KafkaListener(topics = "order-events", groupId = "order-service-group")
-    public void onOrderCreated(ConsumerRecord<String, OrderCreatedEvent> record,
-                                Acknowledgment ack) {
-        try {
-            OrderCreatedEvent event = record.value();
-            log.info("收到订单事件: orderNo={}, partition={}, offset={}",
-                    event.getOrderNo(), record.partition(), record.offset());
-
-            // 处理业务逻辑
-            processOrder(event);
-
-            // 手动确认
-            ack.acknowledge();
-        } catch (Exception e) {
-            log.error("处理订单事件失败: record={}", record, e);
-            // 不确认，消息将被重新消费
-            // 也可以调用 ack.acknowledge() 后将失败消息发送到死信队列
-        }
-    }
-
-    /**
-     * 批量消费
-     */
-    @KafkaListener(topics = "batch-events", groupId = "batch-group",
-            containerFactory = "batchKafkaListenerContainerFactory")
-    public void onBatchMessages(List<ConsumerRecord<String, OrderCreatedEvent>> records,
-                                 Acknowledgment ack) {
-        log.info("批量收到 {} 条消息", records.size());
-        try {
-            for (ConsumerRecord<String, OrderCreatedEvent> record : records) {
-                processOrder(record.value());
-            }
-            ack.acknowledge();
-        } catch (Exception e) {
-            log.error("批量处理消息失败", e);
-        }
-    }
-
-    private void processOrder(OrderCreatedEvent event) {
-        // 业务处理逻辑
-    }
-}
-```
-
-### 多 Topic 消费
-
-```java
-@KafkaListener(topics = {"order-events", "payment-events"},
-        groupId = "notification-group")
-public void onMultipleTopics(ConsumerRecord<String, Object> record, Acknowledgment ack) {
-    String topic = record.topic();
-    switch (topic) {
-        case "order-events" -> handleOrderEvent(record);
-        case "payment-events" -> handlePaymentEvent(record);
-    }
-    ack.acknowledge();
-}
-```
-
-## JSON 序列化/反序列化配置
-
-### 自定义序列化配置
-
-```java
-package com.example.config;
-
-import org.apache.kafka.common.serialization.StringDeserializer;
-import org.apache.kafka.common.serialization.StringSerializer;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.kafka.config.ConcurrentKafkaListenerContainerFactory;
-import org.springframework.kafka.core.*;
-import org.springframework.kafka.support.serializer.JsonDeserializer;
-import org.springframework.kafka.support.serializer.JsonSerializer;
-
-import java.util.HashMap;
-import java.util.Map;
-
-@Configuration
-public class KafkaConfig {
-
-    @Bean
-    public ProducerFactory<String, Object> producerFactory() {
-        Map<String, Object> props = new HashMap<>();
-        props.put(org.apache.kafka.clients.producer.ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
-        props.put(org.apache.kafka.clients.producer.ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
-        props.put(org.apache.kafka.clients.producer.ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, JsonSerializer.class);
-        return new DefaultKafkaProducerFactory<>(props);
-    }
-
-    @Bean
-    public ConsumerFactory<String, Object> consumerFactory() {
-        Map<String, Object> props = new HashMap<>();
-        props.put(org.apache.kafka.clients.consumer.ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
-        props.put(org.apache.kafka.clients.consumer.ConsumerConfig.GROUP_ID_CONFIG, "default-group");
-
-        JsonDeserializer<Object> deserializer = new JsonDeserializer<>();
-        deserializer.addTrustedPackages("com.example.*");
-        deserializer.setUseTypeHeaders(true);
-
-        return new DefaultKafkaConsumerFactory<>(props,
-                new StringDeserializer(), deserializer);
-    }
-
-    @Bean
-    public ConcurrentKafkaListenerContainerFactory<String, Object>
-            kafkaListenerContainerFactory(ConsumerFactory<String, Object> consumerFactory) {
-        ConcurrentKafkaListenerContainerFactory<String, Object> factory =
-                new ConcurrentKafkaListenerContainerFactory<>();
-        factory.setConsumerFactory(consumerFactory);
-        factory.setConcurrency(3);
-        factory.getContainerProperties().setAckMode(
-                org.springframework.kafka.listener.ContainerProperties.AckMode.MANUAL_IMMEDIATE);
-        return factory;
-    }
-}
-```
-
-## 幂等消费模式
-
-### 方式一：数据库唯一键去重
-
-```java
-@Slf4j
-@Component
-@RequiredArgsConstructor
-public class IdempotentOrderConsumer {
-
-    private final OrderService orderService;
-    private final MessageLogMapper messageLogMapper;
-
-    @KafkaListener(topics = "order-events", groupId = "idempotent-group")
-    public void onMessage(ConsumerRecord<String, OrderCreatedEvent> record, Acknowledgment ack) {
-        OrderCreatedEvent event = record.value();
-        String eventId = event.getEventId();
-
-        try {
-            // 1. 检查是否已处理（数据库唯一键）
-            MessageLog existing = messageLogMapper.selectById(eventId);
-            if (existing != null) {
-                log.info("消息已处理，跳过: eventId={}", eventId);
-                ack.acknowledge();
-                return;
-            }
-
-            // 2. 记录消息日志（利用唯一键约束防止并发重复）
-            MessageLog logEntry = new MessageLog();
-            logEntry.setEventId(eventId);
-            logEntry.setTopic(record.topic());
-            logEntry.setContent(JSON.toJSONString(event));
-            logEntry.setStatus("PROCESSING");
-            messageLogMapper.insert(logEntry);
-
-            // 3. 处理业务
-            orderService.processOrder(event);
-
-            // 4. 更新状态
-            logEntry.setStatus("SUCCESS");
-            messageLogMapper.updateById(logEntry);
-
-            ack.acknowledge();
-        } catch (DuplicateKeyException e) {
-            log.info("并发去重，消息已处理: eventId={}", eventId);
-            ack.acknowledge();
-        } catch (Exception e) {
-            log.error("处理消息失败: eventId={}", eventId, e);
-        }
-    }
-}
-```
-
-### 方式二：Redis 去重
-
-```java
-@Slf4j
-@Component
-@RequiredArgsConstructor
-public class RedisIdempotentConsumer {
-
-    private final StringRedisTemplate redisTemplate;
-    private final OrderService orderService;
-
-    private static final String DEDUP_KEY_PREFIX = "avatar:kafka:dedup:";
-    private static final long DEDUP_TTL_HOURS = 24;
-
-    @KafkaListener(topics = "order-events", groupId = "redis-dedup-group")
-    public void onMessage(ConsumerRecord<String, OrderCreatedEvent> record, Acknowledgment ack) {
-        OrderCreatedEvent event = record.value();
-        String dedupKey = DEDUP_KEY_PREFIX + event.getEventId();
-
-        try {
-            // SETNX 原子操作去重
-            Boolean isNew = redisTemplate.opsForValue()
-                    .setIfAbsent(dedupKey, "1", DEDUP_TTL_HOURS, TimeUnit.HOURS);
-
-            if (Boolean.FALSE.equals(isNew)) {
-                log.info("消息已处理（Redis 去重），跳过: eventId={}", event.getEventId());
-                ack.acknowledge();
-                return;
-            }
-
-            // 处理业务
-            orderService.processOrder(event);
-            ack.acknowledge();
-        } catch (Exception e) {
-            log.error("处理消息失败: eventId={}", event.getEventId(), e);
-            // 删除去重标记，允许重试
-            redisTemplate.delete(dedupKey);
-        }
-    }
-}
-```
-
-## 死信队列（DLT）配置
-
-### 使用 DefaultErrorHandler 配置 DLT
-
-```java
-package com.example.config;
-
-import lombok.extern.slf4j.Slf4j;
-import org.apache.kafka.clients.consumer.ConsumerRecord;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.kafka.core.KafkaTemplate;
-import org.springframework.kafka.listener.CommonErrorHandler;
-import org.springframework.kafka.listener.DeadLetterPublishingRecoverer;
-import org.springframework.kafka.listener.DefaultErrorHandler;
-import org.springframework.util.backoff.FixedBackOff;
-
-@Slf4j
-@Configuration
-public class KafkaErrorConfig {
-
-    /**
-     * 配置死信队列处理器
-     * 重试 3 次，每次间隔 1 秒，最终失败发送到 DLT
-     */
-    @Bean
-    public CommonErrorHandler errorHandler(KafkaTemplate<String, Object> kafkaTemplate) {
-        DeadLetterPublishingRecoverer recoverer = new DeadLetterPublishingRecoverer(kafkaTemplate,
-                (record, ex) -> {
-                    log.error("消息处理失败，发送到死信队列: topic={}, key={}, error={}",
-                            record.topic(), record.key(), ex.getMessage());
-                    // 默认发送到 {originalTopic}.DLT
-                    return new org.apache.kafka.common.TopicPartition(
-                            record.topic() + ".DLT", record.partition());
-                });
-
-        // 重试 3 次，间隔 1 秒
-        DefaultErrorHandler errorHandler = new DefaultErrorHandler(recoverer,
-                new FixedBackOff(1000L, 3L));
-
-        // 不重试某些异常
-        errorHandler.addNotRetryableExceptions(
-                IllegalArgumentException.class,
-                com.fasterxml.jackson.core.JsonParseException.class);
-
-        return errorHandler;
-    }
-}
-```
-
-### 消费死信队列
-
-```java
-@Slf4j
-@Component
-public class DeadLetterConsumer {
-
-    @KafkaListener(topics = "order-events.DLT", groupId = "dlt-group")
-    public void onDeadLetter(ConsumerRecord<String, Object> record, Acknowledgment ack) {
-        log.error("收到死信消息: topic={}, key={}, value={}",
-                record.topic(), record.key(), record.value());
-
-        // 记录到数据库或告警系统
-        // alertService.sendAlert("Kafka 死信消息", record.toString());
-
-        ack.acknowledge();
-    }
-}
-```
-
-## Consumer Lag 监控
-
-### 配置 Actuator 监控
-
-```yaml
-management:
-  endpoints:
-    web:
-      exposure:
-        include: health,prometheus,kafka
-  health:
-    kafka:
-      enabled: true  # 启用 Kafka 健康检查
-```
-
-### 使用 Kafka 命令行查看消费延迟
-
-```bash
-# 查看消费者组偏移量和延迟
-kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
-  --group order-service-group --describe
-
-# 重点关注 LAG 列：
-# TOPIC          PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG
-# order-events   0          1000            1050            50
-```
-
-## 最佳实践
-
-### 1. 生产者
-
-- **启用幂等生产**：设置 `enable.idempotence=true`，确保消息不重复发送
-- **设置 acks=all**：等待所有副本确认，保证消息持久化
-- **合理设置 retries**：推荐 3 次，配合 `retry.backoff.ms` 使用
-- **使用 Key 分区**：相同 Key 的消息发送到同一分区，保证顺序性
-
-### 2. 消费者
-
-- **关闭自动提交**：使用手动确认（`enable-auto-commit: false`）
-- **实现幂等消费**：使用数据库唯一键或 Redis 去重
-- **合理设置 concurrency**：消费者并发数不超过分区数
-- **设置 max.poll.interval.ms**：大于业务最大处理时间，避免 rebalance
-
-### 3. Topic 设计
-
-- **合理设置分区数**：根据预期吞吐量，一个分区约 10MB/s
-- **Key 设计**：选择分布均匀的 Key，避免数据倾斜
-- **消息大小**：单条消息不超过 1MB，大数据考虑存 OSS 传引用
-
-### 4. 序列化
-
-- **生产者/消费者序列化一致**：统一使用 JsonSerializer / JsonDeserializer
-- **配置 trusted.packages**：消费端必须配置信任的包路径
-- **消息体增加版本号**：便于后续消息格式升级
-
-## 常见问题
-
-### 1. Consumer Rebalance 频繁
-
-**原因**：消费处理时间超过 `max.poll.interval.ms`
-
-**解决**：
-- 增大 `max.poll.interval.ms` 配置（默认 5 分钟）
-- 减小 `max.poll.records`（每次拉取的消息数）
-- 优化消费逻辑，减少单条消息处理时间
-- 检查 `session.timeout.ms` 和 `heartbeat.interval.ms` 配置
-
-### 2. 反序列化异常
-
-**原因**：生产者和消费者序列化方式不匹配
-
-**解决**：
-- 确保生产者 JsonSerializer 和消费者 JsonDeserializer 版本一致
-- 配置 `spring.json.trusted.packages` 包含消息类的包路径
-- 检查消息类是否有默认构造函数和 getter/setter
-- 旧消息格式变更时使用 `ErrorHandlingDeserializer` 包装
-
-### 3. 消费延迟（Lag）持续增长
-
-**原因**：消费速度跟不上生产速度
-
-**解决**：
-- 增加消费者并发数（`concurrency` 配置）
-- 增加 Topic 分区数（需要先扩分区再加消费者）
-- 优化消费逻辑，使用批量处理
-- 检查是否有单条消息处理时间过长
+---
 
-### 4. 消息丢失
+## 行为准则
 
-**原因**：生产者未确认或消费者自动提交偏移量
+1. **回答要具体**：引用具体的类名、注解、配置项
+2. **主动提醒**：消费者必须做幂等处理，同一分区内消息有序
+3. **使用中文回答**
 
-**解决**：
-- 生产者设置 `acks=all`，启用幂等
-- 消费者关闭自动提交，使用手动确认
-- 检查 Topic 副本因子（推荐 >= 3）
-- 检查 `min.insync.replicas` 配置
+---
 
-### 5. 消息重复消费
+## 文档读取路由
 
-**原因**：消费者 rebalance 或手动提交前崩溃
+> 所有路径相对于 skill 目录 `docs/skills/avatar-boot-starter-kafka-skill/`
 
-**解决**：
-- 实现幂等消费（数据库唯一键或 Redis 去重）
-- 消息体中包含唯一事件 ID
-- 使用 `MANUAL_IMMEDIATE` 确认模式，处理完立即提交
+| 用户需求 | 需读取的文件 |
+|:--|:--|
+| 快速接入 / 发送消息 / 消费消息 / 事务消息 | `references/核心功能.md` |
+| 最佳实践 / 注意事项 | `references/最佳实践.md` |
+| 配置说明 | `references/配置参考.md` |
 
-## 依赖版本
+---
 
-- spring-kafka: 由 Spring Boot 3.5.3 BOM 管理
-- Spring Boot: 3.5.3
-- Java: 21
+## 通用参考信息
 
-## 参考文档
+### 核心配置项
 
-- [Spring for Apache Kafka 官方文档](https://docs.spring.io/spring-kafka/reference/)
-- [Apache Kafka 官方文档](https://kafka.apache.org/documentation/)
-- [Spring Boot Kafka 配置](https://docs.spring.io/spring-boot/reference/messaging/kafka.html)
+| 配置项 | 说明 | 默认值 |
+|:--|:--|:--|
+| `avatar.kafka.bootstrap-servers` | Kafka 服务器地址 | `localhost:9092` |
+| `avatar.kafka.producer.acks` | 确认模式 | `all` |
+| `avatar.kafka.producer.retries` | 重试次数 | `3` |
+| `avatar.kafka.consumer.group-id` | 消费者组 ID | - |
+| `avatar.kafka.consumer.auto-offset-reset` | 偏移量重置策略 | `earliest` |

package/templates/.claude/skills/avatar-boot-starter-kafka/references//346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -0,0 +1,43 @@
+# Kafka 最佳实践与注意事项
+
+## 最佳实践
+
+1. **消息 Key 设计**：使用业务唯一标识作为 Key，保证相关消息的顺序性
+   ```java
+   kafkaTemplate.send("order-topic", order.getOrderId(), JSON.toJSONString(order));
+   ```
+
+2. **幂等处理**：消费者必须做幂等处理，避免重复消费
+   ```java
+   @KafkaListener(topics = "order-topic", groupId = "order-group")
+   public void consume(String message) {
+       String orderId = extractOrderId(message);
+       if (orderService.isProcessed(orderId)) return; // 幂等检查
+       orderService.process(message);
+   }
+   ```
+
+3. **异常处理**：消费失败时记录日志，必要时发送到死信队列
+   ```java
+   @KafkaListener(topics = "order-topic", groupId = "order-group")
+   public void consume(String message) {
+       try {
+           processMessage(message);
+       } catch (Exception e) {
+           log.error("消费失败，发送死信队列: {}", message, e);
+           kafkaTemplate.send("order-topic-dlq", message);
+       }
+   }
+   ```
+
+4. **分区数量**：合理设置分区数量，提高并发消费能力（分区数 = 最大并发消费者数）
+
+5. **监控告警**：监控消息堆积、消费延迟、分区分布等指标
+
+## 注意事项
+
+1. **Topic 创建**：使用前需要创建 Topic，或开启 Kafka 自动创建 Topic
+2. **消费者组**：同一消费者组的实例会负载均衡消费消息，不同组会各自消费全量消息
+3. **消息顺序**：同一分区内的消息保证顺序，不同分区不保证
+4. **偏移量管理**：注意偏移量提交时机，`enable-auto-commit: false` 时需手动提交
+5. **消息大小**：默认最大消息大小 1MB，超大消息需调整 `max.message.bytes`