@pencilps/avatar-boot-cli 1.0.0

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`

package/templates/.claude/skills/avatar-boot-starter-kafka/references//346/240/270/345/277/203/345/212/237/350/203/275.md

@@ -0,0 +1,117 @@
+# Kafka 核心功能
+
+## 1. 添加依赖
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-kafka</artifactId>
+</dependency>
+```
+
+## 2. 配置 Kafka
+
+```yaml
+avatar:
+  kafka:
+    bootstrap-servers: ${KAFKA_SERVERS:localhost:9092}
+    producer:
+      acks: all
+      retries: 3
+      batch-size: 16384
+      buffer-memory: 33554432
+      key-serializer: org.apache.kafka.common.serialization.StringSerializer
+      value-serializer: org.apache.kafka.common.serialization.StringSerializer
+    consumer:
+      group-id: ${spring.application.name}
+      auto-offset-reset: earliest
+      enable-auto-commit: true
+      auto-commit-interval: 1000
+      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
+      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
+```
+
+## 3. 发送消息
+
+```java
+@Resource
+private KafkaTemplate<String, String> kafkaTemplate;
+
+// 同步发送
+SendResult<String, String> result = kafkaTemplate.send(topic, message).get();
+
+// 异步发送
+kafkaTemplate.send(topic, message).addCallback(
+    result -> log.info("发送成功: {}", result.getRecordMetadata().offset()),
+    ex -> log.error("发送失败: {}", ex.getMessage())
+);
+
+// 发送带 Key 的消息（保证相同 Key 进入同一分区）
+kafkaTemplate.send(topic, key, message);
+
+// 批量发送
+messages.forEach(msg -> kafkaTemplate.send(topic, msg));
+```
+
+## 4. 消费消息
+
+```java
+@Component
+public class OrderConsumer {
+
+    // 基础消费
+    @KafkaListener(topics = "order-topic", groupId = "order-consumer-group")
+    public void consume(String message) {
+        // 处理业务逻辑
+    }
+
+    // 消费带 Key 的消息
+    @KafkaListener(topics = "order-topic", groupId = "order-consumer-group")
+    public void consumeWithKey(
+            @Payload String message,
+            @Header(KafkaHeaders.RECEIVED_MESSAGE_KEY) String key) {
+        log.info("Key: {}, Message: {}", key, message);
+    }
+
+    // 批量消费
+    @KafkaListener(topics = "order-topic", groupId = "order-consumer-group")
+    public void consumeBatch(List<String> messages) {
+        messages.forEach(this::processMessage);
+    }
+
+    // 手动提交偏移量（enable-auto-commit: false 时使用）
+    @KafkaListener(topics = "order-topic", groupId = "order-consumer-group")
+    public void consumeManual(String message, Acknowledgment acknowledgment) {
+        try {
+            processMessage(message);
+            acknowledgment.acknowledge(); // 手动提交
+        } catch (Exception e) {
+            log.error("处理失败，不提交偏移量: {}", e.getMessage());
+        }
+    }
+}
+```
+
+## 5. 事务消息
+
+```java
+@Service
+public class OrderService {
+
+    @Resource
+    private KafkaTemplate<String, String> kafkaTemplate;
+
+    @Transactional
+    public void createOrderWithTransaction(Order order) {
+        // 保存订单到数据库
+        orderMapper.insert(order);
+
+        // 在同一事务中发送 Kafka 消息
+        kafkaTemplate.executeInTransaction(operations -> {
+            operations.send("order-topic", JSON.toJSONString(order));
+            operations.send("inventory-topic", JSON.toJSONString(order));
+            return true;
+        });
+    }
+}
+```

package/templates/.claude/skills/avatar-boot-starter-kafka/references//351/205/215/347/275/256/345/217/202/350/200/203.md

@@ -0,0 +1,54 @@
+# Kafka 配置参考
+
+## 完整配置项
+
+```yaml
+avatar:
+  kafka:
+    bootstrap-servers: localhost:9092   # Kafka 服务器地址
+
+    producer:
+      acks: all                         # 确认模式：0/1/all
+      retries: 3                        # 重试次数
+      batch-size: 16384                 # 批量大小（字节）
+      buffer-memory: 33554432           # 缓冲区大小（字节，32MB）
+      key-serializer: org.apache.kafka.common.serialization.StringSerializer
+      value-serializer: org.apache.kafka.common.serialization.StringSerializer
+
+    consumer:
+      group-id: my-consumer-group       # 消费者组 ID（必填）
+      auto-offset-reset: earliest       # 偏移量重置策略：earliest/latest
+      enable-auto-commit: true          # 是否自动提交偏移量
+      auto-commit-interval: 1000        # 自动提交间隔（毫秒）
+      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
+      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
+```
+
+## 配置说明
+
+| 配置项 | 说明 | 默认值 |
+|:--|:--|:--|
+| `bootstrap-servers` | Kafka 服务器地址 | `localhost:9092` |
+| `producer.acks` | 确认模式（0=不确认/1=Leader确认/all=全部确认） | `all` |
+| `producer.retries` | 发送失败重试次数 | `3` |
+| `consumer.group-id` | 消费者组 ID | - |
+| `consumer.auto-offset-reset` | 无偏移量时的策略（earliest从头/latest从最新） | `earliest` |
+| `consumer.enable-auto-commit` | 是否自动提交偏移量 | `true` |
+
+## 多环境配置
+
+```yaml
+# application-dev.yml
+avatar:
+  kafka:
+    bootstrap-servers: localhost:9092
+    consumer:
+      group-id: ${spring.application.name}-dev
+
+# application-prod.yml
+avatar:
+  kafka:
+    bootstrap-servers: ${KAFKA_SERVERS}
+    consumer:
+      group-id: ${spring.application.name}
+```