@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-job/references//347/233/221/346/216/247/346/214/207/346/240/207.md

@@ -0,0 +1,72 @@
+# XXL-Job 监控指标
+
+## 启用监控
+
+监控功能默认启用，需在 `application.yml` 中开启 Prometheus 端点：
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: prometheus,health,info
+  metrics:
+    export:
+      prometheus:
+        enabled: true
+```
+
+禁用监控：
+```yaml
+xxl:
+  job:
+    metrics:
+      enabled: false           # 禁用所有监控
+      execution-enabled: true  # 仅启用任务执行监控
+      executor-enabled: true   # 仅启用执行器状态监控
+```
+
+## 可用指标
+
+### 任务执行指标
+
+| 指标名 | 类型 | 标签 | 说明 |
+|:--|:--|:--|:--|
+| `xxl.job.execution.count` | Counter | `job_handler`, `status` | 执行次数（status: success/failure） |
+| `xxl.job.execution.time` | Timer | `job_handler`, `status` | 执行耗时 |
+| `xxl.job.execution.active` | Gauge | 无 | 当前正在执行的任务数 |
+
+### 执行器状态指标
+
+| 指标名 | 类型 | 标签 | 说明 |
+|:--|:--|:--|:--|
+| `xxl.job.executor.registered` | Gauge | `app_name` | 注册状态（1=已注册，0=未注册） |
+| `xxl.job.executor.handlers.total` | Gauge | `app_name` | 已注册的 JobHandler 总数 |
+
+## Prometheus 查询示例
+
+```promql
+# 任务执行成功率
+sum(rate(xxl_job_execution_count_total{status="success"}[5m]))
+/ sum(rate(xxl_job_execution_count_total[5m])) * 100
+
+# 任务平均执行时间（秒）
+rate(xxl_job_execution_time_seconds_sum[5m])
+/ rate(xxl_job_execution_time_seconds_count[5m])
+
+# 特定任务的失败次数
+sum(xxl_job_execution_count_total{job_handler="demoJobHandler", status="failure"})
+
+# 当前活跃任务数
+xxl_job_execution_active
+
+# P95 执行耗时
+histogram_quantile(0.95, rate(xxl_job_execution_time_seconds_bucket[5m]))
+```
+
+## Grafana 推荐面板
+
+- **任务执行概览**：总执行次数、成功率、平均耗时
+- **任务执行趋势**：按 job_handler 分组的执行次数趋势
+- **执行器状态**：注册状态、Handler 数量、活跃任务数
+- **性能分析**：P95/P99 耗时分布

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

@@ -0,0 +1,580 @@
+---
+name: avatar-boot-starter-kafka
+description: 当涉及 Kafka、消息队列、消息生产、消息消费、事件驱动 相关功能时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于 spring-kafka 的消息队列能力，包含生产者/消费者自动配置、JSON 序列化、死信队列、幂等消费。
+---
+
+Avatar Boot 的 Kafka 消息队列集成模块，基于 spring-kafka（版本由 Spring Boot BOM 管理）提供开箱即用的消息生产和消费能力。
+
+## 功能特性
+
+- ✅ **自动配置** - 基于 Spring Boot 自动配置机制，自动装配 KafkaTemplate 和消费者
+- ✅ **JSON 序列化** - 内置 JSON 序列化/反序列化支持，无缝传输 Java 对象
+- ✅ **消费者组管理** - 支持消费者组和分区分配策略配置
+- ✅ **死信队列** - 内置 DLT（Dead Letter Topic）支持，处理消费失败的消息
+- ✅ **幂等消费** - 提供幂等消费模式，防止消息重复处理
+- ✅ **监控集成** - 集成 Micrometer 指标，监控生产者/消费者状态
+
+## 快速开始
+
+### 1. 添加依赖
+
+在项目的 `pom.xml` 中添加依赖：
+
+```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. 消息丢失
+
+**原因**：生产者未确认或消费者自动提交偏移量
+
+**解决**：
+- 生产者设置 `acks=all`，启用幂等
+- 消费者关闭自动提交，使用手动确认
+- 检查 Topic 副本因子（推荐 >= 3）
+- 检查 `min.insync.replicas` 配置
+
+### 5. 消息重复消费
+
+**原因**：消费者 rebalance 或手动提交前崩溃
+
+**解决**：
+- 实现幂等消费（数据库唯一键或 Redis 去重）
+- 消息体中包含唯一事件 ID
+- 使用 `MANUAL_IMMEDIATE` 确认模式，处理完立即提交
+
+## 依赖版本
+
+- 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)