🤖 go-weixin-ilink：用 Go 给微信 iLink 机器人写业务，就像写 HTTP 路由一样简单

开源地址：github.com/dobest1024/…

---

背景

微信 iLink 开放了机器人接入能力，但官方只有 TypeScript SDK，没有 Go 版本。

如果你的后端是 Go，想接入 iLink 机器人，就需要自己摸索协议——AES 加解密、长轮询、context_token 管理、CDN 媒体上传……踩坑成本不低。

于是我写了这个 SDK，把协议细节全部封装掉，对外只暴露一套简单的 Handler API。

---

最快上手：30 行跑起来一个 Echo Bot

bot := ilink.NewBot(
    ilink.WithTokenFile(".bot-token.json"),
    ilink.WithSyncBufFile(".bot-syncbuf"), // 重启不重放历史消息
)

bot.OnText(func(ctx *ilink.Context) {
    ctx.ReplyText("收到：" + ctx.Text())
})

bot.Login(context.Background(), ilink.TerminalQR) // 终端打印二维码，扫一下
bot.Run(context.Background())

扫码后 token 自动写文件，下次重启不需要再扫。

---

消息路由——告别 if/else 大山

参考 gin 的设计，用声明式路由分发消息：

bot.OnTextPrefix("/help", showHelp)         // 前缀匹配
bot.OnTextContains("关键词", handleKeyword) // 包含匹配
bot.OnTextMatch(`^\d{6}$`, handleCode)      // 正则匹配
bot.OnImage(handleImage)
bot.OnVoice(handleVoice)
bot.OnFile(handleFile)
bot.OnPrivateText(handlePrivate)            // 仅私聊文本
bot.OnGroupText(handleGroup)               // 仅群内文本

---

中间件——洋葱模型，和 gin 一样用

// 日志
bot.Use(func(ctx *ilink.Context) {
    log.Printf("from=%s text=%q", ctx.UserID(), ctx.Text())
    ctx.Next()
})

// 限流：每人每 3 秒 1 条
bot.Use(rateLimiter(3 * time.Second))

// 白名单
bot.Use(func(ctx *ilink.Context) {
    if !whitelist[ctx.UserID()] {
        ctx.ReplyText("无权限")
        ctx.Abort()
        return
    }
    ctx.Next()
})

---

引用消息支持

用户长按消息引用后发送，可以直接读取被引用的内容：

bot.OnText(func(ctx *ilink.Context) {
    if ctx.HasQuote() {
        ctx.ReplyText("你引用了：" + ctx.QuotedText())
        return
    }
    ctx.ReplyText(ctx.Text())
})

---

媒体收发：图片、语音、文件、视频

下载和发送各一行，加解密全在 SDK 内部：

bot.OnImage(func(ctx *ilink.Context) {
    data, _ := ctx.DownloadImage(ctx.Message.GetImageItem())
    result, _ := ctx.Upload(data, "image")
    ctx.ReplyItems([]ilink.MessageItem{ilink.BuildImageItem(result)})
})

---

打字状态

接 AI 接口时，让用户看到"对方正在输入"的体验：

bot.OnText(func(ctx *ilink.Context) {
    ctx.Typing()
    defer ctx.StopTyping()
    ctx.ReplyText(callAI(ctx.Text()))
})

typing_ticket 按用户自动缓存 24 小时，无需手动管理。

---

生产可用的细节

• 断点续传：get_updates_buf 游标持久化到磁盘，重启后从上次位置继续，不丢消息、不重放
• Session 自愈：检测到 -14 session 过期，自动暂停 1 小时后重试，无需人工干预
• Panic 隔离：单条消息 panic 不会让整个轮询崩掉
• 优雅关闭：监听 context 取消，等待 in-flight handler 跑完
• 零依赖：只有标准库，go get 即用

---

存储可替换

内置文件实现，生产环境可以换成 Redis 或数据库：

bot := ilink.NewBot(
    ilink.WithTokenStore(myRedisTokenStore),
    ilink.WithContextTokenStore(myDBCtxStore),
    ilink.WithSyncBufStore(myRedisSyncBuf),
)

---

安装

go get github.com/dobest1024/go-weixin-ilink

需要 Go 1.21+，零外部依赖。

---

适合谁用

• 想快速给微信 iLink 机器人写业务逻辑、不想踩协议坑的 Go 开发者
• 需要接入 AI 模型（Claude、OpenAI 等）作为微信机器人后端的场景
• 企业内部工具、自动化助手、客服机器人等

---

GitHub：github.com/dobest1024/… 欢迎 star、issue 和 PR。