A template for LagrangeGo
基于 LagrangeGo 的Bot 模板参考自MiraiGo-Template
- 使用组合优于继承的设计原则
- 实现依赖注入模式，提高代码可测试性
- 清晰的分层架构，职责分离
- 统一的消息处理器接口，易于扩展
- 中间件支持，横切关注点统一处理
- 事件总线，松耦合的组件通信
- 强大的路由系统，支持多种匹配条件
- 统一的日志系统，支持文件输出和彩色终端
├── app/ # 应用层，依赖注入容器
├── bot/ # Bot层，登录、认证、连接管理
│ ├── auth.go # 认证管理器
│ ├── bot.go # Bot主结构
│ ├── connection.go # 连接管理器
│ ├── login.go # 登录策略
│ └── qrcode.go # 二维码处理器
├── config/ # 配置层
├── logic/ # 逻辑层，消息处理器
│ ├── eventbus.go # 事件总线
│ ├── handlers.go # 示例处理器
│ ├── logic.go # 逻辑管理器
│ ├── matcher.go # 消息匹配器
│ ├── middleware.go # 中间件
│ └── router.go # 路由系统
├── utils/ # 工具层
│ └── log.go # 统一日志系统
├── main.go # 主程序入口
└── application.toml # 配置文件
账号配置application.toml
[bot] # 账号 必填 account = 114514 # 密码 选填 password = "pwd" # 签名服务器 选填 signServer = "https://sign.lagrangecore.org/api/sign/25765"
不配置密码的话将使用扫码登录
git clone https://github.com/ExquisiteCore/LagrangeGo-Template.git
cd LagrangeGo-Template编辑 application.toml 文件，配置你的QQ账号。
在 logic/handlers.go 中注册你的消息处理逻辑：
// RegisterCustomLogic 注册所有自定义逻辑 func RegisterCustomLogic() { // 注册ping命令 Manager.HandleCommand("/", "ping", func(ctx *MessageContext) error { // 处理ping命令 return nil }) // 注册文本匹配处理器 Manager.HandleGroupMessage(func(ctx *MessageContext) error { text := ctx.GetMessageText() if text == "hello" { // 处理hello消息 } return nil }, NewTextMatcher("hello", false)) }
go run main.go
所有消息处理器都需要实现 MessageHandler 接口：
type MessageHandler interface { Handle(ctx *MessageContext) error }
LogicManager 提供了多种便捷方法：
// 处理命令 Manager.HandleCommand("/", "ping", handlerFunc) // 处理私聊消息 Manager.HandlePrivateMessage(handlerFunc, matchers...) // 处理群消息 Manager.HandleGroupMessage(handlerFunc, matchers...) // 处理好友请求 Manager.HandleFriendRequest(handlerFunc, matchers...)
支持多种匹配条件：
// 文本匹配 NewTextMatcher("hello", false) // 正则匹配 NewRegexMatcher(`^\d+$`) // 前缀匹配 NewPrefixMatcher("/") // 发送者匹配 NewSenderMatcher(12345, 67890) // 群聊匹配 NewGroupMatcher(111111, 222222) // 命令匹配 NewCommandMatcher("/", "ping", "help") // 组合匹配 NewAndMatcher(matcher1, matcher2) NewOrMatcher(matcher1, matcher2)
- LoggingMiddleware: 请求日志记录
- RecoveryMiddleware: 错误恢复
- RateLimitMiddleware: 频率限制
- AuthMiddleware: 权限验证
- MetricsMiddleware: 指标收集
// 全局中间件 Manager.UseMiddleware(LoggingMiddleware()) Manager.UseMiddleware(RecoveryMiddleware()) // 路由中间件 Manager.HandleCommand("/", "admin", handlerFunc, AuthMiddleware([]uint32{12345}), RateLimitMiddleware(5, time.Minute), )
项目内置事件总线，支持异步事件处理：
// 订阅事件 Manager.GetEventBus().Subscribe(EventTypeCommandExecuted, func(ctx context.Context, event Event) error { // 处理命令执行事件 return nil }) // 发布事件 PublishMessageReceived(msgContext) PublishCommandExecuted(msgContext, "ping")
EventTypeMessageReceived: 消息接收事件EventTypeMessageProcessed: 消息处理完成事件EventTypeCommandExecuted: 命令执行事件EventTypeError: 错误事件
config := &utils.LogConfig{ Level: utils.InfoLevel, EnableFile: true, EnableColor: true, LogDir: "logs", LogFile: "bot.log", MaxSize: 10, // MB MaxBackups: 5, MaxAge: 30, // days Format: "text", // text or json } utils.InitWithConfig(config)
// 基础日志 utils.Info("这是一条信息") utils.Infof("用户 %d 发送了消息", userID) // 带字段的日志 utils.WithField("user_id", 12345).Info("用户操作") utils.WithFields(map[string]interface{}{ "user_id": 12345, "action": "login", }).Info("用户登录")
支持多种登录方式：
- FastLoginStrategy: 快速登录（使用保存的签名）
- QRCodeLoginStrategy: 二维码登录
- 自动重连机制
- 连接状态监控
- 心跳包发送
- 连接事件处理
- 签名文件管理
- 自动加载和保存
- 签名有效性检查
使用依赖注入容器管理所有组件：
container := app.NewContainer() err := container.Initialize() bot := container.GetBot() logicManager := container.GetLogicManager() client := container.GetClient() config := container.GetConfig()
- 创建处理器结构体
- 实现
MessageHandler接口 - 在
RegisterCustomLogic中注册
- 实现
Middleware函数类型 - 在需要的路由上使用
- 实现
Matcher接口 - 在路由中使用
- 定义事件类型常量
- 创建事件结构体
- 发布和订阅事件
go build -o bot ../bot
FROM golang:1.21-alpine AS builder WORKDIR /app COPY . . RUN go mod download RUN go build -o bot . FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=builder /app/bot . COPY --from=builder /app/application.toml . CMD ["./bot"]
- LagrangeGo - 核心协议库
- logrus - 日志库
- toml - 配置文件解析
- qrterminal - 终端二维码显示
- qrcode - 二维码解析
- colorable - 跨平台彩色终端
MIT License
欢迎提交 Issue 和 Pull Request！
- 重构整个架构，采用组合优于继承
- 实现依赖注入模式
- 新增强大的路由系统和中间件支持
- 添加事件总线机制
- 统一日志系统
- 完善的错误处理和重连机制
- 初始版本
- 基础消息处理功能