QQ Bot (qqbot)

基于 Go 语言 + 官方 botgo SDK 的 QQ 机器人，使用 WebSocket 模式连接 QQ 开放平台，无需域名备案和 HTTPS 证书。

特性

• WebSocket 长连接 — 避开 Webhook 模式的域名备案要求
• 单进程部署 — 代码全部在一个二进制中，无需额外服务
• 自动重连 — SDK 内置 SessionManager，连接断开自动恢复
• Token 自动刷新 — access token 过期前自动续期，无需手动管理
• 统一日志 — 基于 uber-go/zap 的结构化日志，标准库 log 和 SDK 内部日志统一接管

快速开始

前置条件

• Go 1.21+
• QQ 开放平台的机器人 AppID 和 AppSecret（前往申请）

1. 克隆项目

git clone <repo-url> qqbot
cd qqbot

2. 修改配置

编辑 config.yaml，填入你的凭证：

app_id: "your_app_id_here"
app_secret: "your_app_secret_here"

也可以用环境变量（优先级高于配置文件）：

export QQBOT_APP_ID="your_app_id"
export QQBOT_APP_SECRET="your_app_secret"

3. 编译运行

make build   # 编译到 bin/qqbot
make run     # 编译并运行

项目结构

qqbot/
├── main.go              # 入口：初始化日志 → 配置 → token → WebSocket
├── config/
│   └── config.go        # 配置结构体 + YAML 加载 + 环境变量覆盖
├── handler/
│   └── handler.go       # C2C 私聊 / 群 @ 消息处理器 + BuildReply 业务逻辑
├── pkg/
│   └── logger/
│       └── logger.go    # zap 封装：Logger 接口 + 标准库 log 重定向
├── tests/
│   ├── handler_test.go  # BuildReply 单元测试（12 表驱动 + 优先级 + 大小写）
│   └── config_test.go   # Config.Load 单元测试（4 场景）
├── config.yaml          # 配置文件模板
├── Makefile             # 构建 / 测试 / 运行 / 清理
└── bin/                 # 编译产物目录（gitignore）

配置参考

字段	类型	默认值	说明
app_id	string	—	必填，机器人 AppID
app_secret	string	—	必填，机器人 AppSecret
sandbox	bool	false	是否使用沙箱环境
logger.level	string	info	日志级别：debug / info / warn / error
logger.mode	string	production	development（彩色大写级别）/ production（小写）
logger.format	string	console	控制台格式：console / json
logger.file_path	string	""	日志文件路径，留空仅输出到控制台

环境变量

变量	覆盖字段
QQBOT_APP_ID	app_id
QQBOT_APP_SECRET	app_secret
QQBOT_LOG_LEVEL	logger.level

Make 命令

make              # 编译（默认）
make build        # 编译到 bin/qqbot
make debug        # 调试构建（关闭优化，配合 dlv）
make release      # 生产构建（去除符号 + 压缩）
make run          # 编译并运行
make test         # 运行单元测试（详细输出）
make test-short   # 运行单元测试（精简输出）
make vet          # 代码静态检查
make fmt          # 代码格式化
make tidy         # 整理 go.mod / go.sum
make clean        # 清理编译产物
make help         # 显示所有命令

自定义业务逻辑

编辑 handler/handler.go 中的 BuildReply 函数即可：

func BuildReply(content string) string {
    // 在这里写你的消息处理逻辑
    // 返回的字符串会作为回复发送给用户
}

更复杂的场景（调用外部 API、数据库查询等）建议在 handler 中新增函数，保持结构清晰。

依赖

依赖	用途
botgo v0.2.1	官方 QQ 机器人 Go SDK
zap v1.27.0	结构化日志
yaml.v3	YAML 配置文件解析

License

MIT