@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

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

@@ -0,0 +1,662 @@
+---
+name: avatar-boot-starter-rocketmq
+description: 当涉及 RocketMQ、消息队列、延迟消息、事务消息、顺序消息 相关功能时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于 rocketmq-spring-boot-starter 2.3.1 的消息队列能力，包含生产者/消费者自动配置、延迟消息、事务消息、顺序消费。
+---
+
+Avatar Boot 的 RocketMQ 消息队列集成模块，基于 rocketmq-spring-boot-starter 2.3.1 提供开箱即用的消息生产和消费能力。
+
+## 功能特性
+
+- ✅ **自动配置** - 基于 Spring Boot 自动配置机制，自动装配 RocketMQTemplate
+- ✅ **注解驱动** - 使用 @RocketMQMessageListener 注解快速定义消费者
+- ✅ **延迟消息** - 支持 18 个等级的延迟消息投递
+- ✅ **事务消息** - 支持分布式事务消息，保证本地事务与消息发送的一致性
+- ✅ **顺序消息** - 支持分区有序和全局有序消息消费
+- ✅ **Tag 过滤** - 支持基于 Tag 的消息过滤，灵活路由消息
+- ✅ **重试机制** - 内置消费重试策略，支持自定义重试次数
+
+## 快速开始
+
+### 1. 添加依赖
+
+在项目的 `pom.xml` 中添加依赖：
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-rocketmq</artifactId>
+</dependency>
+```
+
+> 版本由 Avatar Boot BOM 统一管理，无需指定 version。内置 rocketmq-spring-boot-starter 2.3.1。
+
+### 2. 配置文件
+
+在 `application.yml` 中添加 RocketMQ 配置：
+
+```yaml
+rocketmq:
+  name-server: localhost:9876                    # NameServer 地址
+  producer:
+    group: ${spring.application.name}-producer   # 生产者组名
+    send-message-timeout: 3000                   # 发送超时时间（毫秒）
+    retry-times-when-send-failed: 2              # 同步发送失败重试次数
+    retry-times-when-send-async-failed: 2        # 异步发送失败重试次数
+    max-message-size: 4194304                    # 最大消息大小（4MB）
+    compress-message-body-threshold: 4096        # 消息压缩阈值（4KB）
+```
+
+### 3. 发送第一条消息
+
+```java
+package com.example.producer;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.rocketmq.spring.core.RocketMQTemplate;
+import org.springframework.stereotype.Service;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class SimpleProducer {
+
+    private final RocketMQTemplate rocketMQTemplate;
+
+    public void sendMessage(String topic, String message) {
+        rocketMQTemplate.convertAndSend(topic, message);
+        log.info("消息发送成功: topic={}, message={}", topic, message);
+    }
+}
+```
+
+### 4. 消费第一条消息
+
+```java
+package com.example.consumer;
+
+import lombok.extern.slf4j.Slf4j;
+import org.apache.rocketmq.spring.annotation.RocketMQMessageListener;
+import org.apache.rocketmq.spring.core.RocketMQListener;
+import org.springframework.stereotype.Component;
+
+@Slf4j
+@Component
+@RocketMQMessageListener(
+        topic = "test-topic",
+        consumerGroup = "test-consumer-group"
+)
+public class SimpleConsumer implements RocketMQListener<String> {
+
+    @Override
+    public void onMessage(String message) {
+        log.info("收到消息: {}", message);
+        // 处理业务逻辑
+    }
+}
+```
+
+## 生产者详解
+
+### 同步发送
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderProducer {
+
+    private final RocketMQTemplate rocketMQTemplate;
+
+    /**
+     * 同步发送（等待 Broker 确认）
+     */
+    public void syncSend(OrderEvent event) {
+        SendResult result = rocketMQTemplate.syncSend("order-topic", event);
+        log.info("同步发送结果: msgId={}, status={}", result.getMsgId(), result.getSendStatus());
+    }
+
+    /**
+     * 同步发送（带 Tag）
+     */
+    public void syncSendWithTag(OrderEvent event, String tag) {
+        // destination 格式: topic:tag
+        SendResult result = rocketMQTemplate.syncSend("order-topic:" + tag, event);
+        log.info("发送结果: msgId={}, tag={}", result.getMsgId(), tag);
+    }
+
+    /**
+     * 同步发送（带超时和延迟级别）
+     */
+    public void syncSendWithTimeout(OrderEvent event) {
+        SendResult result = rocketMQTemplate.syncSend("order-topic",
+                MessageBuilder.withPayload(event).build(),
+                3000);  // 超时 3 秒
+        log.info("发送结果: {}", result);
+    }
+}
+```
+
+### 异步发送
+
+```java
+@Service
+@RequiredArgsConstructor
+public class AsyncProducer {
+
+    private final RocketMQTemplate rocketMQTemplate;
+
+    /**
+     * 异步发送（不阻塞当前线程）
+     */
+    public void asyncSend(OrderEvent event) {
+        rocketMQTemplate.asyncSend("order-topic", event, new SendCallback() {
+            @Override
+            public void onSuccess(SendResult sendResult) {
+                log.info("异步发送成功: msgId={}", sendResult.getMsgId());
+            }
+
+            @Override
+            public void onException(Throwable e) {
+                log.error("异步发送失败: event={}", event, e);
+                // 补偿处理：入库重试、告警
+            }
+        });
+    }
+
+    /**
+     * 单向发送（不需要确认，最快但不保证送达）
+     */
+    public void onewaySend(LogEvent event) {
+        rocketMQTemplate.sendOneWay("log-topic", event);
+    }
+}
+```
+
+### 批量发送
+
+```java
+@Service
+@RequiredArgsConstructor
+public class BatchProducer {
+
+    private final RocketMQTemplate rocketMQTemplate;
+
+    /**
+     * 批量发送消息
+     */
+    public void batchSend(List<OrderEvent> events) {
+        List<Message<OrderEvent>> messages = events.stream()
+                .map(event -> MessageBuilder.withPayload(event).build())
+                .collect(Collectors.toList());
+
+        SendResult result = rocketMQTemplate.syncSend("order-topic", messages, 5000);
+        log.info("批量发送结果: {}", result);
+    }
+}
+```
+
+## 消费者详解
+
+### 基本消费
+
+```java
+@Slf4j
+@Component
+@RocketMQMessageListener(
+        topic = "order-topic",
+        consumerGroup = "order-consumer-group",
+        consumeMode = ConsumeMode.CONCURRENTLY,     // 并发消费（默认）
+        messageModel = MessageModel.CLUSTERING,      // 集群模式（默认）
+        consumeThreadNumber = 20                     // 消费线程数
+)
+public class OrderConsumer implements RocketMQListener<OrderEvent> {
+
+    @Override
+    public void onMessage(OrderEvent event) {
+        log.info("收到订单事件: orderNo={}", event.getOrderNo());
+        // 处理业务逻辑
+        // 抛出异常会触发重试
+    }
+}
+```
+
+### 带 Tag 过滤的消费
+
+```java
+@Slf4j
+@Component
+@RocketMQMessageListener(
+        topic = "order-topic",
+        consumerGroup = "order-create-group",
+        selectorType = SelectorType.TAG,
+        selectorExpression = "CREATE || UPDATE"  // 只消费 CREATE 和 UPDATE 标签的消息
+)
+public class OrderCreateConsumer implements RocketMQListener<OrderEvent> {
+
+    @Override
+    public void onMessage(OrderEvent event) {
+        log.info("收到订单创建/更新事件: {}", event);
+    }
+}
+```
+
+### 消费原始 MessageExt
+
+```java
+@Slf4j
+@Component
+@RocketMQMessageListener(
+        topic = "order-topic",
+        consumerGroup = "order-ext-group"
+)
+public class OrderExtConsumer implements RocketMQListener<MessageExt> {
+
+    @Override
+    public void onMessage(MessageExt messageExt) {
+        String msgId = messageExt.getMsgId();
+        int reconsumeTimes = messageExt.getReconsumeTimes();
+        String body = new String(messageExt.getBody(), StandardCharsets.UTF_8);
+
+        log.info("收到消息: msgId={}, 重试次数={}, body={}", msgId, reconsumeTimes, body);
+
+        if (reconsumeTimes >= 3) {
+            // 超过重试次数，记录到数据库人工处理
+            log.error("消息重试超过 3 次，进入人工处理: msgId={}", msgId);
+            return;
+        }
+
+        // 处理业务逻辑
+    }
+}
+```
+
+## 延迟消息
+
+RocketMQ 支持 18 个延迟级别：
+
+| 级别 | 延迟时间 | 级别 | 延迟时间 |
+|------|---------|------|---------|
+| 1 | 1s | 10 | 6min |
+| 2 | 5s | 11 | 7min |
+| 3 | 10s | 12 | 8min |
+| 4 | 30s | 13 | 9min |
+| 5 | 1min | 14 | 10min |
+| 6 | 2min | 15 | 20min |
+| 7 | 3min | 16 | 30min |
+| 8 | 4min | 17 | 1h |
+| 9 | 5min | 18 | 2h |
+
+### 发送延迟消息
+
+```java
+@Service
+@RequiredArgsConstructor
+public class DelayMessageProducer {
+
+    private final RocketMQTemplate rocketMQTemplate;
+
+    /**
+     * 发送延迟消息
+     * @param delayLevel 延迟级别（1-18）
+     */
+    public void sendDelayMessage(String topic, Object payload, int delayLevel) {
+        Message<?> message = MessageBuilder.withPayload(payload).build();
+        // syncSend(destination, message, timeout, delayLevel)
+        SendResult result = rocketMQTemplate.syncSend(topic, message, 3000, delayLevel);
+        log.info("延迟消息发送成功: msgId={}, delayLevel={}", result.getMsgId(), delayLevel);
+    }
+
+    /**
+     * 订单超时取消：30 分钟后检查（延迟级别 16）
+     */
+    public void sendOrderTimeoutCheck(String orderNo) {
+        OrderTimeoutEvent event = new OrderTimeoutEvent(orderNo, LocalDateTime.now());
+        Message<?> message = MessageBuilder.withPayload(event).build();
+        rocketMQTemplate.syncSend("order-timeout-topic", message, 3000, 16);
+        log.info("订单超时检查消息已发送: orderNo={}, 30 分钟后触发", orderNo);
+    }
+}
+```
+
+### 消费延迟消息
+
+```java
+@Slf4j
+@Component
+@RocketMQMessageListener(
+        topic = "order-timeout-topic",
+        consumerGroup = "order-timeout-group"
+)
+public class OrderTimeoutConsumer implements RocketMQListener<OrderTimeoutEvent> {
+
+    @Autowired
+    private OrderService orderService;
+
+    @Override
+    public void onMessage(OrderTimeoutEvent event) {
+        log.info("收到订单超时检查: orderNo={}", event.getOrderNo());
+        // 检查订单是否已支付，未支付则取消
+        orderService.cancelIfUnpaid(event.getOrderNo());
+    }
+}
+```
+
+## 事务消息
+
+### 事务消息流程
+
+1. 生产者发送半事务消息（Half Message）到 Broker
+2. Broker 存储成功后回调本地事务执行
+3. 本地事务执行成功，提交消息；失败，回滚消息
+4. Broker 定期回查未确认的事务消息状态
+
+### 发送事务消息
+
+```java
+@Service
+@RequiredArgsConstructor
+public class TransactionalProducer {
+
+    private final RocketMQTemplate rocketMQTemplate;
+
+    /**
+     * 发送事务消息
+     */
+    public void sendTransactionalMessage(OrderEvent event) {
+        Message<OrderEvent> message = MessageBuilder
+                .withPayload(event)
+                .setHeader("orderNo", event.getOrderNo())
+                .build();
+
+        // 发送事务消息
+        TransactionSendResult result = rocketMQTemplate.sendMessageInTransaction(
+                "order-tx-topic", message, event);
+
+        log.info("事务消息发送结果: msgId={}, localTxState={}",
+                result.getMsgId(), result.getLocalTransactionState());
+    }
+}
+```
+
+### 实现本地事务监听器
+
+```java
+package com.example.listener;
+
+import com.example.event.OrderEvent;
+import com.example.service.OrderService;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.rocketmq.spring.annotation.RocketMQTransactionListener;
+import org.apache.rocketmq.spring.core.RocketMQLocalTransactionListener;
+import org.apache.rocketmq.spring.core.RocketMQLocalTransactionState;
+import org.springframework.messaging.Message;
+import org.springframework.stereotype.Component;
+
+@Slf4j
+@Component
+@RocketMQTransactionListener
+@RequiredArgsConstructor
+public class OrderTransactionListener implements RocketMQLocalTransactionListener {
+
+    private final OrderService orderService;
+
+    /**
+     * 执行本地事务
+     * 半事务消息发送成功后回调
+     */
+    @Override
+    public RocketMQLocalTransactionState executeLocalTransaction(Message msg, Object arg) {
+        OrderEvent event = (OrderEvent) arg;
+        try {
+            log.info("执行本地事务: orderNo={}", event.getOrderNo());
+            // 执行本地数据库操作
+            orderService.createOrderLocal(event);
+            return RocketMQLocalTransactionState.COMMIT;  // 提交消息
+        } catch (Exception e) {
+            log.error("本地事务执行失败: orderNo={}", event.getOrderNo(), e);
+            return RocketMQLocalTransactionState.ROLLBACK;  // 回滚消息
+        }
+    }
+
+    /**
+     * 事务回查
+     * Broker 未收到确认时定期回查
+     */
+    @Override
+    public RocketMQLocalTransactionState checkLocalTransaction(Message msg) {
+        String orderNo = (String) msg.getHeaders().get("orderNo");
+        log.info("事务回查: orderNo={}", orderNo);
+
+        // 查询本地事务是否已执行
+        boolean exists = orderService.existsByOrderNo(orderNo);
+        if (exists) {
+            return RocketMQLocalTransactionState.COMMIT;
+        }
+        return RocketMQLocalTransactionState.UNKNOWN;  // 继续回查
+    }
+}
+```
+
+## 顺序消息
+
+### 发送顺序消息
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderlyProducer {
+
+    private final RocketMQTemplate rocketMQTemplate;
+
+    /**
+     * 发送顺序消息
+     * 相同 hashKey 的消息发送到同一队列，保证顺序
+     */
+    public void sendOrderly(String topic, Object payload, String hashKey) {
+        SendResult result = rocketMQTemplate.syncSendOrderly(topic, payload, hashKey);
+        log.info("顺序消息发送成功: msgId={}, queue={}", result.getMsgId(),
+                result.getMessageQueue().getQueueId());
+    }
+
+    /**
+     * 订单状态变更：同一订单的状态变更消息保证顺序
+     */
+    public void sendOrderStatusChange(String orderNo, String status) {
+        OrderStatusEvent event = new OrderStatusEvent(orderNo, status, LocalDateTime.now());
+        // 使用 orderNo 作为 hashKey，保证同一订单消息有序
+        rocketMQTemplate.syncSendOrderly("order-status-topic", event, orderNo);
+    }
+}
+```
+
+### 顺序消费
+
+```java
+@Slf4j
+@Component
+@RocketMQMessageListener(
+        topic = "order-status-topic",
+        consumerGroup = "order-status-group",
+        consumeMode = ConsumeMode.ORDERLY  // 顺序消费模式
+)
+public class OrderStatusConsumer implements RocketMQListener<OrderStatusEvent> {
+
+    @Override
+    public void onMessage(OrderStatusEvent event) {
+        log.info("顺序收到订单状态变更: orderNo={}, status={}",
+                event.getOrderNo(), event.getStatus());
+        // 按顺序处理订单状态变更
+    }
+}
+```
+
+## Tag 消息过滤
+
+### 发送带 Tag 的消息
+
+```java
+@Service
+@RequiredArgsConstructor
+public class TagProducer {
+
+    private final RocketMQTemplate rocketMQTemplate;
+
+    public void sendWithTag(OrderEvent event, OrderAction action) {
+        // destination 格式: topic:tag
+        String destination = "order-topic:" + action.name();
+        rocketMQTemplate.syncSend(destination, event);
+    }
+}
+
+public enum OrderAction {
+    CREATE, UPDATE, CANCEL, COMPLETE
+}
+```
+
+### 按 Tag 过滤消费
+
+```java
+// 只消费创建和取消的订单消息
+@RocketMQMessageListener(
+        topic = "order-topic",
+        consumerGroup = "order-alert-group",
+        selectorType = SelectorType.TAG,
+        selectorExpression = "CREATE || CANCEL"
+)
+public class OrderAlertConsumer implements RocketMQListener<OrderEvent> {
+    @Override
+    public void onMessage(OrderEvent event) {
+        // 仅处理 CREATE 和 CANCEL 标签的消息
+    }
+}
+```
+
+## 重试策略配置
+
+### 消费重试
+
+RocketMQ 默认消费失败重试 16 次，重试间隔逐步增大：
+
+| 重试次数 | 间隔时间 | 重试次数 | 间隔时间 |
+|---------|---------|---------|---------|
+| 1 | 10s | 9 | 7min |
+| 2 | 30s | 10 | 8min |
+| 3 | 1min | 11 | 9min |
+| 4 | 2min | 12 | 10min |
+| 5 | 3min | 13 | 20min |
+| 6 | 4min | 14 | 30min |
+| 7 | 5min | 15 | 1h |
+| 8 | 6min | 16 | 2h |
+
+### 自定义重试次数
+
+```java
+@RocketMQMessageListener(
+        topic = "order-topic",
+        consumerGroup = "order-retry-group",
+        maxReconsumeTimes = 5  // 最大重试 5 次
+)
+public class RetryConsumer implements RocketMQListener<MessageExt> {
+
+    @Override
+    public void onMessage(MessageExt msg) {
+        if (msg.getReconsumeTimes() >= 3) {
+            log.warn("消息重试 {} 次，进入补偿流程: msgId={}", msg.getReconsumeTimes(), msg.getMsgId());
+            // 入库人工处理
+            return;
+        }
+        // 正常业务处理，抛出异常会自动重试
+    }
+}
+```
+
+## 最佳实践
+
+### 1. 生产者
+
+- **设置合理的超时时间**：`send-message-timeout` 建议 3-5 秒
+- **启用重试**：同步和异步发送各设置 2-3 次重试
+- **使用 Tag 分类消息**：便于消费端按需过滤
+- **消息体控制大小**：单条消息不超过 4MB，大数据存 OSS 传引用
+
+### 2. 消费者
+
+- **幂等消费**：根据业务唯一标识（如订单号）去重
+- **异常处理**：合理使用重试机制，超过重试次数入库人工处理
+- **消费线程数**：`consumeThreadNumber` 根据业务类型设置，IO 密集型可设大
+- **避免长时间消费**：单条消息处理时间建议不超过 15 秒
+
+### 3. Topic 设计
+
+- **按业务域划分 Topic**：如 order-topic、payment-topic、user-topic
+- **使用 Tag 区分操作**：如 CREATE、UPDATE、DELETE
+- **Topic 命名规范**：`{应用名}-{业务域}-topic`
+
+### 4. 事务消息
+
+- **本地事务要快**：避免在 executeLocalTransaction 中执行耗时操作
+- **回查逻辑要幂等**：checkLocalTransaction 可能被多次调用
+- **记录事务状态**：本地事务执行后记录状态，便于回查
+
+## 常见问题
+
+### 1. 消息发送超时
+
+**原因**：NameServer 或 Broker 不可达
+
+**解决**：
+- 检查 `rocketmq.name-server` 配置是否正确
+- 检查网络连通性：`telnet nameserver-host 9876`
+- 增大 `send-message-timeout` 配置
+- 检查 Broker 是否正常运行
+
+### 2. 消费者无法消费消息
+
+**原因**：消费者组名冲突或 Topic 不存在
+
+**解决**：
+- 检查 `consumerGroup` 是否唯一（不同 Topic 不能使用相同消费者组）
+- 检查 Topic 是否已创建
+- 检查 selectorExpression（Tag 过滤表达式）是否正确
+- 查看消费者日志是否有注册成功的信息
+
+### 3. 消息堆积
+
+**原因**：消费速度跟不上生产速度
+
+**解决**：
+- 增大 `consumeThreadNumber`（消费线程数）
+- 优化消费逻辑，减少单条消息处理时间
+- 临时扩容消费者实例
+- 检查是否有消费异常导致重试堆积
+
+### 4. 事务消息一直 UNKNOWN
+
+**原因**：`checkLocalTransaction` 无法确认事务状态
+
+**解决**：
+- 确保本地事务执行后有持久化状态可查
+- 检查回查逻辑是否正确查询了本地事务状态
+- 设置合理的事务回查间隔和次数
+
+### 5. 顺序消息乱序
+
+**原因**：消费端并发消费或消费失败重试
+
+**解决**：
+- 确保 `consumeMode = ConsumeMode.ORDERLY`
+- 避免消费异常导致的重试打乱顺序
+- 确保使用正确的 hashKey 发送到同一队列
+
+## 依赖版本
+
+- rocketmq-spring-boot-starter: 2.3.1
+- Spring Boot: 3.5.3
+- Java: 21
+
+## 参考文档
+
+- [RocketMQ Spring 官方文档](https://github.com/apache/rocketmq-spring)
+- [Apache RocketMQ 官方文档](https://rocketmq.apache.org/docs/)
+- [RocketMQ 最佳实践](https://rocketmq.apache.org/docs/bestPractice/01bestpractice/)