go-lark: Golang 飞书与Lark开放平台易用SDK插件库

go-lark 是一个用于飞书和Lark开放平台的易用SDK，实现了消息API，全面支持构建聊天机器人和通知机器人。

特性

• 支持通知机器人和聊天机器人
• 发送消息（群组、私聊、富文本和卡片）
• 使用 MsgBuffer 快速构建消息
• 轻松创建接收消息的钩子
• 支持加密和令牌验证
• 支持Gin和Hertz Web框架的中间件
• 高度可扩展
• 完善的文档和测试

安装

go get github.com/go-lark/lark

快速开始

前提条件

go-lark支持两种类型的机器人，需要手动创建：

聊天机器人:

• 飞书: 从飞书开放平台创建
• Lark: 从Lark开发者平台创建
• 需要App ID和App Secret来初始化ChatBot

通知机器人:

• 从群聊创建
• 需要Web Hook URL

发送消息

聊天机器人:

import "github.com/go-lark/lark"

func main() {
    bot := lark.NewChatBot("<App ID>", "<App Secret>")
    bot.StartHeartbeat()
    bot.PostText("hello, world", lark.WithEmail("someone@example.com"))
}

通知机器人:

import "github.com/go-lark/lark"

func main() {
    bot := lark.NewNotificationBot("<WEB HOOK URL>")
    bot.PostNotificationV2(lark.NewMsgBuffer(lark.MsgText).Text("hello, world").Build())
}

切换到Lark端点

默认API端点是飞书的，要切换到Lark，应使用SetDomain:

bot := lark.NewChatBot("<App ID>", "<App Secret>")
bot.SetDomain(lark.DomainLark)

使用示例

认证

自动续期认证:

// 使用appID和appSecret初始化聊天机器人
bot := lark.NewChatBot(appID, appSecret)
// 定期续期访问令牌
bot.StartHeartbeat()
// 停止续期
bot.StopHeartbeat()

单次认证:

bot := lark.NewChatBot(appID, appSecret)
resp, err := bot.GetTenantAccessTokenInternal(true)
// 现在可以通过`bot.TenantAccessToken()`访问令牌值

消息发送

对于聊天机器人，可以使用以下方法发送简单消息:

• PostText
• PostTextMention
• PostTextMentionAll
• PostImage
• PostShareChatCard
• ReplyMessage
• AddReaction
• DeleteReaction

要构建富文本消息，可以使用消息缓冲区(或简称为MsgBuffer)，它通过链式方法方便地构建消息。

消息缓冲区

我们可以使用MsgBuffer构建消息体，并使用PostMessage发送，支持以下消息类型:

• MsgText: 文本
• MsgPost: 富文本
• MsgInteractive: 交互式卡片
• MsgShareCard: 群组分享卡片
• MsgShareUser: 用户分享卡片
• MsgImage: 图片
• MsgFile: 文件
• MsgAudio: 音频
• MsgMedia: 媒体
• MsgSticker: 贴纸

MsgBuffer提供绑定函数和内容函数。

绑定函数:

内容函数与消息内容类型配对。如果不匹配，则无法成功发送。

中间件

我们已经实现了HTTP中间件来支持事件处理:

• Gin中间件
• Hertz中间件

URL挑战:

r := gin.Default()
middleware := larkgin.NewLarkMiddleware()
middleware.BindURLPrefix("/handle") // 假设URL是http://your.domain.com/handle
r.Use(middleware.LarkChallengeHandler())

事件V2:

Lark提供了事件v2，它自动应用于新创建的机器人。

r := gin.Default()
middleware := larkgin.NewLarkMiddleware()
r.Use(middleware.LarkEventHandler())

获取事件(例如消息):

r.POST("/", func(c *gin.Context) {
    if evt, ok := middleware.GetEvent(c); ok { // => 使用GetEvent而不是GetMessage
        if evt.Header.EventType == lark.EventTypeMessageReceived {
            if msg, err := evt.GetMessageReceived(); err == nil {
                fmt.Println(msg.Message.Content)
            }
        }
    }
})

卡片回调:

我们也可以为卡片操作(如按钮)设置回调。URL挑战部分相同。

我们可以使用LarkCardHandler来处理操作:

r.Use(middleware.LarkCardHandler())
r.POST("/callback", func(c *gin.Context) {
    if card, ok := middleware.GetCardCallback(c); ok {
    }
})

接收消息(事件V1):

对于旧版机器人，请使用v1:

r := gin.Default()
middleware := larkgin.NewLarkMiddleware()
middleware.BindURLPrefix("/handle") // 假设URL是http://your.domain.com/handle
r.POST("/handle", func(c *gin.Context) {
    if msg, ok := middleware.GetMessage(c); ok && msg != nil {
        text := msg.Event.Text
        // 你的业务逻辑
    }
})

安全与加密

Lark开放平台提供AES加密和令牌验证以确保事件安全。

• AES加密: 开启后，所有流量将使用AES加密
• 令牌验证: 对传入消息进行简单的令牌验证

我们建议你启用令牌验证。如果你的主机上没有HTTPS，则启用AES加密。

middleware.WithTokenVerfication("<verification-token>")
middleware.WithEncryption("<encryption-key>")

完整示例

发送富文本消息

package main

import (
    "github.com/go-lark/lark"
)

func main() {
    // 初始化聊天机器人
    bot := lark.NewChatBot("your_app_id", "your_app_secret")
    bot.StartHeartbeat()
    
    // 构建富文本消息
    mb := lark.NewMsgBuffer(lark.MsgPost)
    mb.Post(lark.NewPostBuilder().
        Title("富文本消息标题").
        TextTag("这是一条", 1, true).
        TextTag("富文本", 1, true).
        TextTag("消息", 1, true).
        LinkTag("点击这里", "https://example.com").
        AtTag("someone@example.com", "某人").
        Build())
    
    // 发送消息到指定邮箱
    _, err := bot.PostMessage(mb.BindEmail("someone@example.com").Build())
    if err != nil {
        panic(err)
    }
}

接收并处理消息

package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
    "github.com/go-lark/lark-gin"
    "github.com/go-lark/lark"
)

func main() {
    r := gin.Default()
    
    // 初始化中间件
    middleware := larkgin.NewLarkMiddleware()
    middleware.WithTokenVerfication("your_verification_token")
    
    // 处理URL挑战
    r.Use(middleware.LarkChallengeHandler())
    
    // 处理消息事件
    r.Use(middleware.LarkEventHandler())
    
    r.POST("/", func(c *gin.Context) {
        if evt, ok := middleware.GetEvent(c); ok {
            if evt.Header.EventType == lark.EventTypeMessageReceived {
                if msg, err := evt.GetMessageReceived(); err == nil {
                    fmt.Printf("收到消息: %s\n", msg.Message.Content)
                    
                    // 回复消息
                    bot := lark.NewChatBot("your_app_id", "your_app_secret")
                    bot.ReplyMessage(msg.Message.MessageID, lark.NewMsgBuffer(lark.MsgText).Text("已收到你的消息").Build())
                }
            }
        }
    })
    
    r.Run(":8080")
}

发送交互式卡片

package main

import (
    "github.com/go-lark/lark"
    "github.com/go-lark/lark/card"
)

func main() {
    // 初始化聊天机器人
    bot := lark.NewChatBot("your_app_id", "your_app_secret")
    bot.StartHeartbeat()
    
    // 构建交互式卡片
    cardContent := card.NewCardBuilder().
        Header("卡片标题", "blue").
        AddElement(card.NewMarkdownElement("这是一张**交互式**卡片")).
        AddAction(card.NewButtonElement("点击按钮", "primary", map[string]interface{}{
            "value": map[string]interface{}{"key": "value"},
        })).
        Build()
    
    // 发送卡片消息
    mb := lark.NewMsgBuffer(lark.MsgInteractive)
    mb.Card(cardContent)
    
    _, err := bot.PostMessage(mb.BindEmail("someone@example.com").Build())
    if err != nil {
        panic(err)
    }
}

常见问题

• 发送消息时收到99991401错误
  • 从仪表板移除IP白名单
• 机器人发送消息失败
  1. 检查认证
  2. 未邀请到群组
  3. 未申请API权限
• go-lark支持交互式消息卡片吗?
  • 是的，使用CardBuilder

贡献

• 如果你认为发现了go-lark的bug，请提交issue
• 欢迎Pull Request

许可证

Copyright © David Zhang, 2018-2024. 遵循MIT许可证。