@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

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

@@ -0,0 +1,101 @@
+# RocketMQ 核心功能
+
+## 1. 添加依赖
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-rocketmq</artifactId>
+</dependency>
+```
+
+## 2. 配置 RocketMQ
+
+```yaml
+rocketmq:
+  name-server: 127.0.0.1:9876
+  producer:
+    group: my-producer-group
+    send-message-timeout: 3000
+```
+
+> 不需要 `@EnableRocketMQ` 注解，引入依赖自动配置。
+
+## 3. 发送消息
+
+```java
+@Resource
+private RocketMQProducer rocketMQProducer;
+
+// 同步发送（等待结果）
+rocketMQProducer.sendSync("test-topic", "test-tag", "Hello RocketMQ");
+
+// 异步发送（不阻塞）
+rocketMQProducer.sendAsync("test-topic", "test-tag", "Hello Async");
+
+// 单向发送（不关心结果，最高性能）
+rocketMQProducer.sendOneWay("test-topic", "test-tag", "Hello OneWay");
+
+// 延迟消息（第4个参数为延迟级别，3=10秒）
+rocketMQProducer.sendDelayed("test-topic", "test-tag", "Delayed Message", 3);
+```
+
+## 4. 消费消息
+
+```java
+// 消费字符串消息
+@Component
+@RocketMQMessageListener(
+    topic = "test-topic",
+    consumerGroup = "my-consumer-group",
+    selectorExpression = "test-tag"  // Tag 过滤，* 表示所有
+)
+public class TestConsumer implements RocketMQListener<String> {
+
+    @Override
+    public void onMessage(String message) {
+        log.info("收到消息: {}", message);
+        // 处理业务逻辑
+    }
+}
+
+// 消费对象消息（自动反序列化）
+@Component
+@RocketMQMessageListener(
+    topic = "order-topic",
+    consumerGroup = "order-consumer-group"
+)
+public class OrderConsumer implements RocketMQListener<Order> {
+
+    @Override
+    public void onMessage(Order order) {
+        log.info("收到订单: {}", order.getOrderId());
+    }
+}
+
+// 顺序消费
+@Component
+@RocketMQMessageListener(
+    topic = "order-topic",
+    consumerGroup = "order-seq-group",
+    consumeMode = ConsumeMode.ORDERLY  // 顺序消费
+)
+public class OrderSeqConsumer implements RocketMQListener<String> {
+
+    @Override
+    public void onMessage(String message) {
+        // 同一队列内的消息按顺序处理
+    }
+}
+```
+
+## 延迟级别速查
+
+| 级别 | 时间 | 级别 | 时间 |
+|:--|:--|:--|:--|
+| 1 | 1秒 | 10 | 6分钟 |
+| 2 | 5秒 | 11 | 7分钟 |
+| 3 | 10秒 | 14 | 10分钟 |
+| 4 | 30秒 | 16 | 30分钟 |
+| 5 | 1分钟 | 17 | 1小时 |
+| 6 | 2分钟 | 18 | 2小时 |

package/templates/.claude/skills/avatar-boot-starter-rocketmq/references//351/205/215/347/275/256/344/270/216/346/263/250/346/204/217/344/272/213/351/241/271.md

@@ -0,0 +1,44 @@
+# RocketMQ 配置与注意事项
+
+## 完整配置
+
+```yaml
+rocketmq:
+  name-server: 127.0.0.1:9876          # NameServer 地址（必填）
+  producer:
+    group: my-producer-group            # 生产者组名（必填）
+    send-message-timeout: 3000          # 发送超时时间（毫秒）
+  reliability:
+    enabled: false                      # 启用消息可靠性投递（默认 false）
+```
+
+## 消费者注解参数
+
+| 参数 | 说明 | 默认值 |
+|:--|:--|:--|
+| `topic` | 主题名称 | - |
+| `consumerGroup` | 消费者组名 | - |
+| `selectorExpression` | Tag 过滤表达式（`*` 表示所有） | `*` |
+| `messageModel` | 消息模式（CLUSTERING/BROADCASTING） | `CLUSTERING` |
+| `consumeMode` | 消费模式（CONCURRENTLY/ORDERLY） | `CONCURRENTLY` |
+
+## 注意事项
+
+1. **无需 @EnableRocketMQ**：引入依赖自动配置，不需要在启动类添加注解
+
+2. **消费者幂等**：RocketMQ 自带重试机制，消费者**必须**实现幂等处理，防止重复消费
+
+3. **异常处理**：消费者抛出异常会触发 RocketMQ 重试，谨慎捕获异常后不抛出
+
+4. **消息大小**：单条消息不超过 4MB
+
+5. **幂等性依赖 Redis**：`MessageIdempotentClient` 需要 Redis 支持，未配置 Redis 时自动禁用，不会报错
+
+6. **顺序消费**：使用 `consumeMode = ConsumeMode.ORDERLY` 保证同一队列内顺序消费，但会降低并发性能
+
+## 最佳实践
+
+1. **Tag 过滤**：合理使用 Tag 减少无效消费，同一 Topic 下不同业务用不同 Tag 区分
+2. **消费者组命名**：使用有意义的名称，如 `{服务名}-{业务}-consumer-group`
+3. **批量发送**：大量消息使用批量发送提高性能
+4. **死信队列**：消费多次失败后消息进入死信队列（`%DLQ%{consumerGroup}`），需监控处理

package/templates/.claude/skills/avatar-boot-starter-rocketmq/references//351/253/230/347/272/247/347/211/271/346/200/247.md

@@ -0,0 +1,71 @@
+# RocketMQ 高级特性
+
+## 消息幂等性（可选，需要 Redis）
+
+**启用条件**：配置了 Redis 连接信息，`MessageIdempotentClient` 自动检测 `RedissonClient` Bean，未配置 Redis 时自动禁用。
+
+```java
+@Resource
+private MessageIdempotentClient idempotentClient;
+
+@Component
+@RocketMQMessageListener(topic = "order-topic", consumerGroup = "order-group")
+public class OrderConsumer implements RocketMQListener<String> {
+
+    @Override
+    public void onMessage(String message) {
+        String messageId = extractMessageId(message); // 从消息中提取唯一ID
+
+        // 幂等检查
+        if (idempotentClient.isProcessed(messageId)) {
+            log.warn("消息已处理，跳过: {}", messageId);
+            return;
+        }
+
+        try {
+            processMessage(message);
+            // 标记为已处理（保留 7 天）
+            idempotentClient.markProcessed(messageId, Duration.ofDays(7));
+        } catch (Exception e) {
+            log.error("消息处理失败", e);
+            throw e; // 抛出异常触发 RocketMQ 重试
+        }
+    }
+}
+```
+
+## 消息可靠性投递（可选，基于本地文件）
+
+**启用方式**：
+```yaml
+rocketmq:
+  reliability:
+    enabled: true
+```
+
+**工作原理**：
+1. 发送前：消息保存到本地文件（`~/.avatar/mq/messages/`，状态：PENDING）
+2. 发送成功：更新状态为 SENT
+3. 发送失败：记录失败原因，等待重试
+4. 自动补偿：定时任务每分钟扫描 PENDING 消息并重试
+5. 指数退避：重试间隔 60s → 120s → 240s → 480s → 960s
+6. 自动清理：每天凌晨 2 点清理 7 天前已发送的消息
+
+**消息文件格式**（`~/.avatar/mq/messages/{messageId}.json`）：
+```json
+{
+  "messageId": "abc123",
+  "topic": "test-topic",
+  "tag": "test-tag",
+  "content": "Hello RocketMQ",
+  "status": "PENDING",
+  "retryCount": 0,
+  "maxRetryCount": 5,
+  "nextRetryTime": "2026-03-11T10:00:00"
+}
+```
+
+**特点**：
+- 零侵入，不需要创建数据库表
+- 消息存储在本地文件，重启后自动恢复
+- 适合对消息丢失敏感的业务场景