# qqbot-starter

**Repository Path**: wang-guanru/qqbot-starter

## Basic Information

- **Project Name**: qqbot-starter
- **Description**: QQ机器人springboot-starter
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-23
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QQBot Starter

🤖 一个简单易用的Spring Boot Starter，用于快速集成QQ机器人API调用功能。

## ✨ 特性

- **开箱即用** - 添加依赖即可使用，无需复杂配置
- **多机器人支持** - 一个项目可配置多个QQ机器人
- **完整消息类型** - 支持文本、图片、卡片、Markdown等消息类型
- **自动文件上传** - 图片消息支持URL自动上传
- **类型安全** - 强类型配置，IDE智能提示
- **设计模式优化** - 使用策略模式、建造者模式等，易于扩展

## 📦 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>com.github.rmyx</groupId>
    <artifactId>qqbot-starter</artifactId>
    <version>latest</version>
</dependency>
```

### 2. 配置文件

在 `application.yml` 中配置你的机器人信息：

```yaml
qqbot:
  enabled: true
  default-bot: "bot1"  # 默认使用的机器人
  bots:
    bot1:  # 机器人标识
      appId: "你的AppId"
      appSecret: "你的AppSecret"
      botQQ: 123456789
      name: "主机器人"
    bot2:
      appId: "另一个AppId"
      appSecret: "另一个AppSecret"
      botQQ: 987654321
      name: "备用机器人"
```

### 3. 使用示例

```java
@RestController
public class BotController {
    
    @Autowired
    private QQBotClient qqBotClient;
    
    @GetMapping("/send-text")
    public String sendText() {
        // 使用默认机器人发送文本消息
        return qqBotClient.sendTextMessage("Hello World!", "群组OpenId");
    }
}
```

## 📋 功能详解

### 群聊文本消息

```java
// 使用默认机器人
qqBotClient.sendTextMessage("消息内容", "群组OpenId");

// 指定机器人AppId
qqBotClient.sendTextMessage("消息内容", "群组OpenId", "指定AppId");

// 通过指定的AppId发送
qqBotClient.sendTextMessage("消息内容", "群组OpenId", "102694979");

// 完整参数
qqBotClient.sendTextMessage("消息内容", "群组OpenId", "AppId", "回复消息Id", 序号);
```

### 单聊文本消息

```java
// 使用默认机器人
qqBotClient.sendUserTextMessage("消息内容", "用户OpenId");

// 指定机器人AppId
qqBotClient.sendUserTextMessage("消息内容", "用户OpenId", "指定AppId");

// 通过指定的AppId发送
qqBotClient.sendUserTextMessage("消息内容", "用户OpenId", "102694979");

// 完整参数
qqBotClient.sendUserTextMessage("消息内容", "用户OpenId", "AppId", "回复消息Id", 序号);
```

### 群聊图片消息

```java
// 通过图片URL发送（推荐 - 自动上传）
qqBotClient.sendImageByUrl("https://example.com/image.jpg", "图片描述", "群组OpenId");

// 指定机器人AppId
qqBotClient.sendImageByUrl("https://example.com/image.jpg", "图片描述", "群组OpenId", "AppId");

// 使用已上传的媒体对象
Object media = uploadedMediaObject;
qqBotClient.sendImageMessage(media, "图片描述", "群组OpenId");

// 通过指定的AppId发送
qqBotClient.sendImageByUrl("图片URL", "描述", "群组OpenId", "102694979");
```

### 单聊图片消息

```java
// 通过图片URL发送（推荐 - 自动上传）
qqBotClient.sendUserImageByUrl("https://example.com/image.jpg", "图片描述", "用户OpenId");

// 指定机器人AppId
qqBotClient.sendUserImageByUrl("https://example.com/image.jpg", "图片描述", "用户OpenId", "AppId");

// 使用已上传的媒体对象
Object media = uploadedMediaObject;
qqBotClient.sendUserImageMessage(media, "图片描述", "用户OpenId");

// 通过指定的AppId发送
qqBotClient.sendUserImageByUrl("图片URL", "描述", "用户OpenId", "102694979");
```


### 群聊ARK卡片消息

```java
// 构建卡片参数
List<ArkModel.ArkParam> params = Arrays.asList(
    new ArkModel.ArkParam("#TITLE#", "卡片标题"),
    new ArkModel.ArkParam("#DESC#", "卡片描述"),
    new ArkModel.ArkParam("#IMG#", "图片URL"),
    new ArkModel.ArkParam("#LINK#", "链接地址")
);

// 发送群聊ARK卡片消息
qqBotClient.sendArkMessage(24, params, "群组OpenId");
```

### 单聊ARK卡片消息

```java
// 构建卡片参数
List<ArkModel.ArkParam> params = Arrays.asList(
    new ArkModel.ArkParam("#TITLE#", "卡片标题"),
    new ArkModel.ArkParam("#DESC#", "卡片描述"),
    new ArkModel.ArkParam("#IMG#", "图片URL"),
    new ArkModel.ArkParam("#LINK#", "链接地址")
);

// 发送单聊ARK卡片消息
qqBotClient.sendUserArkMessage(24, params, "用户OpenId");
```

### 群聊Markdown消息

```java
// 构建Markdown参数
List<MarkdownModel.MarkdownParam> params = Arrays.asList(
    new MarkdownModel.MarkdownParam("key1", Arrays.asList("value1", "value2"))
);

// 发送群聊Markdown消息（带键盘）
qqBotClient.sendMarkdownMessage("模板Id", params, "键盘Id", "群组OpenId");
```

### 单聊Markdown消息

```java
// 构建Markdown参数
List<MarkdownModel.MarkdownParam> params = Arrays.asList(
    new MarkdownModel.MarkdownParam("key1", Arrays.asList("value1", "value2"))
);

// 发送单聊Markdown消息（带键盘）
qqBotClient.sendUserMarkdownMessage("模板Id", params, "键盘Id", "用户OpenId");
```

### 高级用法 - 使用Builder构建复杂消息

```java
// 使用Builder构建文本消息
QQMessage textMessage = QQMessage.builder()
    .content("复杂消息内容")
    .msgType(MessageType.TEXT)
    .groupOpenId("群组OpenId")
    .appId("AppId")
    .msgId("回复的消息Id")
    .msgSeq(1)
    .build();

String messageId = qqBotClient.sendMessage(textMessage);

// 使用Builder构建图片消息（通过URL）
QQMessage imageMessage = QQMessage.builder()
    .content("图片描述")
    .msgType(MessageType.IMAGE)
    .groupOpenId("群组OpenId")
    .appId("AppId")
    .imageUrl("https://example.com/image.jpg")  // 自动上传
    .build();

qqBotClient.sendMessage(imageMessage);

// 使用Builder构建图片消息（使用已上传media）
QQMessage mediaMessage = QQMessage.builder()
    .content("图片描述")
    .msgType(MessageType.IMAGE)
    .groupOpenId("群组OpenId")
    .appId("AppId")
    .media(uploadedMediaObject)  // 已上传的媒体对象
    .build();

qqBotClient.sendMessage(mediaMessage);
```

## 🔧 配置说明

### 基础配置

| 配置项 | 说明 | 默认值 | 必填 |
|--------|------|--------|------|
| `qqbot.enabled` | 是否启用QQBot功能 | `true` | 否 |
| `qqbot.default-bot` | 默认使用的机器人Key | 无 | 否 |

### 机器人配置

| 配置项 | 说明 | 必填 |
|--------|------|------|
| `qqbot.bots.[key].appId` | 机器人的AppId | 是 |
| `qqbot.bots.[key].appSecret` | 机器人的AppSecret | 是 |
| `qqbot.bots.[key].botQQ` | 机器人的QQ号 | 是 |
| `qqbot.bots.[key].name` | 机器人名称（用于标识） | 否 |

### 完整配置示例

```yaml
qqbot:
  enabled: true
  default-bot: "main"
  bots:
    main:
      appId: "102692983"
      appSecret: "your-app-secret"
      botQQ: 3889603116
      name: "主机器人"
    backup:
      appId: "102694979"
      appSecret: "backup-app-secret"
      botQQ: 3889605001
      name: "备用机器人"
```

## 🎯 最佳实践

### 1. 多机器人场景

```java
@Service
public class BotService {
    
    @Autowired
    private QQBotClient qqBotClient;
    
    public void sendNotification(String content, String groupId) {
        try {
            // 优先使用主机器人
            qqBotClient.sendTextMessage(content, groupId, "102692983");
        } catch (Exception e) {
            // 主机器人失败时使用备用机器人
            qqBotClient.sendTextMessage(content, groupId, "102694979");
        }
    }
}
```

### 2. 消息发送封装

```java
@Component
public class MessageHelper {
    
    @Autowired
    private QQBotClient qqBotClient;
    
    public String sendRichMessage(String groupId, String title, String content, String imageUrl) {
        if (imageUrl != null) {
            return qqBotClient.sendImageByUrl(imageUrl, title + "\n" + content, groupId);
        } else {
            return qqBotClient.sendTextMessage(title + "\n" + content, groupId);
        }
    }
}
```

### 3. 异常处理

```java
@Service
public class SafeBotService {
    
    @Autowired
    private QQBotClient qqBotClient;
    
    public boolean sendSafeMessage(String content, String groupId) {
        try {
            String messageId = qqBotClient.sendTextMessage(content, groupId);
            return messageId != null;
        } catch (Exception e) {
            log.error("发送消息失败: {}", e.getMessage());
            return false;
        }
    }
}
```

## 🏗️ 架构设计

项目采用了多种设计模式：

- **策略模式** - 不同消息类型使用不同的发送策略
- **建造者模式** - QQMessage支持Builder模式构建
- **模板方法模式** - AbstractMessageSender统一发送流程
- **依赖注入** - Spring IoC容器管理所有组件

## 🐛 常见问题

### Q: 提示找不到QQBotClient Bean？
A: 确保配置文件正确，检查`qqbot.enabled=true`

### Q: Token获取失败？
A: 检查AppId和AppSecret是否正确，网络是否正常

### Q: 图片发送失败？
A: 确保图片URL可访问，或检查上传的media对象格式

### Q: 多机器人如何选择？
A: 可以通过botKey指定，或设置default-bot

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📞 支持

如有问题，请提交Issue或联系作者。