qbot

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

README

qbot

qbot 是 QQ 机器人单聊和群聊的 Go SDK,提供 Access Token 管理、文本发送及 Webhook 消息接收。

HTTP 契约参考 腾讯 API v2 文档,回调与沙箱地址参考 tencent-connect/botgo。项目结构见 项目地图。

环境与安装

需要 Go 1.27 或更高版本:

go get github.com/go-sdk/qbot

机器人需在开放平台创建,并由调用方完成沙箱成员、接口权限、出口 IP 白名单、HTTPS 回调地址和事件监听配置。SDK 不修改开放平台配置。

创建客户端

client := qbot.New(
	qbot.WithAppID(appID),
	qbot.WithAppSecret(appSecret),
	qbot.WithTimeout(15*time.Second),
)

New 不发送请求,也不启动后台协程。每次发送前自动取得 Token;同一 Client 的并发调用共享成功的刷新结果,等待刷新的调用可以通过 Context 取消。缓存通常在到期前 60 秒刷新;有效期不足 600 秒时,刷新提前量为有效期的十分之一。凭证仅保存在内存中。

需要提前检查凭证时可调用:

token, err := client.GetAccessToken(ctx)
if err != nil {
	return err
}
// token.ExpiresAt 是缓存凭证的实际到期时间,不应打印 token.AccessToken。
_ = token.ExpiresAt

GetAccessToken 返回副本。ExpiresIn 是服务端最初返回的有效秒数,并非读取缓存时的剩余秒数。SDK 无损兼容其 JSON 数字与字符串表示。

由应用统一管理 Token 时,使用 WithToken(accessToken);该配置优先于 AppID/AppSecret,SDK 不刷新静态 Token,其有效期字段为零。创建 Webhook Handler 时仍需 AppSecret。

发送文本

单聊使用 author.user_openid,群聊使用 group_openid;不要把群成员的 member_openid 用作单聊目标,不同 AppID 的 OpenID 也不能互换。

回复单聊消息:

result, err := client.SendText(ctx, qbot.SendTextRequest{
	ToUserID:        message.Author.UserOpenID,
	Text:            "收到",
	MessageID:       message.ID,
	MessageSequence: 1,
})
if err != nil {
	return err
}
_ = result.MessageID

回复群聊消息:

result, err := client.SendGroupText(ctx, qbot.SendGroupTextRequest{
	GroupID:         message.GroupID,
	Text:            "收到",
	MessageID:       message.ID,
	MessageSequence: 1,
})
if err != nil {
	return err
}
_ = result.MessageID

MessageID 对应 msg_id,取入站消息内层的 d.id;EventID 对应 event_id,取外层事件 id。二者互斥。只有平台支持回复的事件才能使用 EventID,普通消息回复应使用 MessageID。

MessageSequence 为零时发送 1。对同一消息多次回复时,由调用方递增序号;同一个 msg_id + msg_seq 重复发送会被平台去重。SDK 不分配或持久化回复序号。

不填写 MessageID 和 EventID 即为主动发送,仍受机器人权限、用户或群的主动消息开关及配额限制。被动回复也受服务端时效和次数限制;SDK 不在本地硬编码这些平台规则。文本保持原始内容,空白文本会被拒绝。

成功响应包含 MessageID、Timestamp、ExtInfo.ReferenceIndex 和 HTTP TraceID。SDK 检查 HTTP 状态和业务码,并要求发送响应含消息 ID;请求失败后不自动刷新重发,不自动重试消息发送。

接收消息

创建处理器并挂载到现有 HTTP 服务:

handler, err := client.WebhookHandler(func(ctx context.Context, message qbot.Message) error {
	if message.Content == "" {
		return nil
	}
	switch message.EventType {
	case qbot.EventC2CMessageCreate:
		_, err := client.SendText(ctx, qbot.SendTextRequest{
			ToUserID:  message.Author.UserOpenID,
			Text:      "收到",
			MessageID: message.ID,
		})
		return err
	case qbot.EventGroupATMessageCreate, qbot.EventGroupMessageCreate:
		_, err := client.SendGroupText(ctx, qbot.SendGroupTextRequest{
			GroupID:   message.GroupID,
			Text:      "收到",
			MessageID: message.ID,
		})
		return err
	}
	return nil
})
if err != nil {
	return err
}
mux.Handle("/qqbot", handler)

代码中的 ctx、凭证、message 和 mux 由应用提供。示例展示接口衔接,应用应在回复前实现去重,避免重投时重复产生业务副作用。

Handler 支持以下消息事件:

事件 常量 场景
C2C_MESSAGE_CREATE EventC2CMessageCreate QQ 单聊
GROUP_AT_MESSAGE_CREATE EventGroupATMessageCreate 群内 @ 机器人
GROUP_MESSAGE_CREATE EventGroupMessageCreate 群全量消息,需要平台权限及配置

每次请求都先验证 X-Signature-Ed25519 / X-Signature-Timestamp 和原始 Body,包括 op=13 的地址验证。验签失败返回 HTTP 401;非法 JSON、缺少必要消息字段或不支持的 Opcode 返回 HTTP 400。Body 上限为 1 MiB,不依赖 Content-Length。

地址验证通过后返回 plain_token 及其签名;心跳返回 op=11。消息处理函数返回 nil 时返回 {"op":12,"d":0},返回错误时返回 {"op":12,"d":1},由平台决定是否重投。其他事件类型验签后直接成功确认,不调用消息处理函数。回调响应不包含业务处理错误详情,调用方需要在自己的处理函数中记录适当的错误元数据。

HTTP 请求之间可能并发处理,同一事件或消息也可能重复投递。SDK 不串行化、不持久化、不去重,不承诺恰好处理一次;由应用结合 EventID、消息 ID 及回复序号管理幂等性。SDK 不启动 HTTP 服务或后台消费任务。耗时业务应在应用可靠接收后交给其队列处理,再返回成功确认。

Client 配置

  • 默认消息 API:https://api.bot.qq.com。
  • Token 固定入口:https://api.bot.qq.com/app/getAppAccessToken,不受消息地址覆盖影响。
  • WithSandbox() 使用 botgo 定义的 https://sandbox.api.sgroup.qq.com;Token 入口不变,平台沙箱是否可用需以当前账号配置及真实调用为准。
  • WithBaseURL(url) 覆盖消息地址;与 WithSandbox() 同时使用时,后传入的地址配置生效。
  • WithTimeout 默认 15 秒,覆盖一次 API 调用的总预算,包括等待 Token、刷新和消息请求,调用方更短的 Context 优先生效。
  • WithClient 复用自定义 core/restx.Client 的代理、传输和调试配置。SDK 使用前应完成配置,使用期间不要并发修改该客户端或重新应用 Options。
  • 默认地址只接受 HTTPS;可信开发环境可以显式使用 WithInsecureHTTP() 允许明文消息 API。

SDK 不配置自动重试;通过自定义 restx 客户端启用的重试、请求 Hook 和调试日志由调用方负责。调试可能暴露 Authorization、AppSecret、消息和媒体链接,应根据应用的敏感信息策略控制。

错误处理

通过 core/errx 判断错误类别和读取服务端元数据:

switch {
case errx.Is(err, qbot.ErrUnauthorized):
	// HTTP 401;调用方检查或更新凭证。
case errx.Is(err, qbot.ErrRateLimited):
	// HTTP 429;调用方决定退避。
case errx.Is(err, qbot.ErrHTTPStatus):
	// 非 2xx HTTP 状态。
case errx.Is(err, qbot.ErrProtocol):
	// 非零业务错误码、非法 JSON 或缺少必要响应字段。
case errx.Is(err, qbot.ErrRequest):
	// DNS、连接或 TLS 等请求失败。
}

var apiErr *qbot.APIError
if errx.As(err, &apiErr) {
	// 可以读取 apiErr.HTTPStatus、apiErr.Code 和 apiErr.TraceID。
}

Token 接口检查 code,消息接口兼容 err_code 和 code。业务错误可能发生在 HTTP 200,判断业务分支时应读取 APIError.Code;ErrUnauthorized / ErrRateLimited 仅映射对应 HTTP 状态。APIError 可同时匹配 HTTP 状态和业务错误类别。

Context 取消或超时直接返回对应 Context 错误。SDK 的错误不包含凭证、消息、原始请求 URL 查询信息、服务端错误正文或完整响应。

支持边界

  • 支持 Access Token 缓存及按需刷新、调用方管理的静态 Token、沙箱和自定义消息地址。
  • 支持单聊和群聊纯文本主动发送、消息回复和平台允许的事件回复。
  • 支持 Webhook 地址验证、验签、心跳和上述三种消息事件。
  • 保留消息附件元数据,不下载、上传或发送媒体。
  • 不实现频道、频道私信、WebSocket、Markdown、键盘、消息撤回及其他管理 API。
  • 不持久化凭证和消息,不管理 HTTP 服务生命周期、平台配置、事件去重、回复序号或发送配额。

开发

make lint
go build ./...

本地测试通过以下命令显式执行:

make test

本地测试使用自定义 HTTP Transport 及 httptest.NewRecorder,不访问真实 QQ 接口,也不启动监听服务。make test 和直接运行 go test 都会继承环境变量;真实测试默认跳过,只有对应环境变量开关为 1 时才执行。静态检查、编译和本地测试均不能证明真实账号鉴权、平台回调、主动消息权限或发送配额。

真实接口测试

真实测试不启动服务、不测试 Webhook 回调。以下三个入口各自只执行对应测试:

命令 开关 实际行为
make test-network QBOT_NETWORK_TESTS=1 获取真实 Access Token,不发送消息
make test-send QBOT_SEND_TESTS=1 向指定用户发送一条文本
make test-send-group QBOT_GROUP_SEND_TESTS=1 向指定群发送一条文本

鉴权测试必须提供开放平台 AppID 和 AppSecret,即使已有 QBOT_ACCESS_TOKEN 也会验证凭证获取:

export QBOT_APP_ID="<AppID>"
export QBOT_APP_SECRET="<AppSecret>"

make test-network

发送测试使用已有 QBOT_ACCESS_TOKEN,为空时使用 QBOT_APP_ID / QBOT_APP_SECRET 自动获取。下列命令会分别发送真实消息:

export QBOT_ACCESS_TOKEN="<可选,已有 Access Token>"
export QBOT_TO_USER_ID="<单聊用户 user_openid>"

make test-send
export QBOT_GROUP_ID="<群 group_openid>"

make test-send-group

可选发送参数:

环境变量 默认行为
QBOT_TEXT 空值时发送 测试消息 加本地 RFC3339 时间
QBOT_BASE_URL 空值时使用默认正式环境;沙箱可设置为 https://sandbox.api.sgroup.qq.com
QBOT_MESSAGE_ID 被动回复的消息 ID,空值时不携带
QBOT_EVENT_ID 平台允许回复的事件 ID,与 QBOT_MESSAGE_ID 互斥
QBOT_MESSAGE_SEQUENCE 无符号 32 位整数;空值或零使用 SDK 默认序号 1

不提供消息 ID 和事件 ID 时执行主动发送,受平台权限、主动消息开关和配额限制。被动回复应提供当前目标的有效消息或事件 ID;再次回复同一消息时需要递增序号。

测试使用 30 秒超时,显式关闭 HTTP 调试,鉴权成功只记录有效期,发送成功只记录返回的消息 ID 和追踪 ID,不输出凭证、目标 OpenID 或文本内容。测试不会重试发送;请仅在准备好真实凭证和目标后显式执行。

Documentation

Overview

Package qbot 提供 QQ 机器人单聊和群聊的 Access Token 管理、文本发送与 Webhook 接收能力。

SDK 不启动 HTTP 服务,不持久化凭证、事件或消息序号。 调用方负责开放平台配置、HTTP 服务生命周期、消息去重及被动回复序号。 频道、WebSocket、媒体上传下载和富媒体消息发送不在当前支持范围内。

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrAppIDRequired          = errx.New("app id is required")
	ErrAppSecretRequired      = errx.New("app secret is required")
	ErrUserIDRequired         = errx.New("user openid is required")
	ErrGroupIDRequired        = errx.New("group openid is required")
	ErrInvalidTarget          = errx.New("invalid message target")
	ErrTextRequired           = errx.New("text is required")
	ErrInvalidReply           = errx.New("message id and event id are mutually exclusive")
	ErrMessageHandlerRequired = errx.New("message handler is required")
	ErrInvalidURL             = errx.New("invalid api url")
	ErrRequest                = errx.New("qq request failed")
	ErrHTTPStatus             = errx.New("unexpected http status")
	ErrProtocol               = errx.New("qq protocol error")
	ErrUnauthorized           = errx.New("qq authentication failed")
	ErrRateLimited            = errx.New("qq rate limit exceeded")
	ErrInvalidSignature       = errx.New("invalid webhook signature")
)

Functions

This section is empty.

Types

type APIError

type APIError struct {
	HTTPStatus int
	Code       int
	TraceID    string
}

APIError 保留服务端状态、业务错误码和追踪 ID,不保留可能包含敏感数据的错误正文。 errx.Is 可判断错误类别,errx.As 可取得这些元数据。

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

type AccessTokenResponse

type AccessTokenResponse struct {
	AccessToken string    `json:"access_token"`
	ExpiresIn   int64     `json:"expires_in"`
	ExpiresAt   time.Time `json:"-"`
}

AccessTokenResponse 返回凭证及其有效期;静态 Token 的有效期字段为零。 ExpiresIn 是服务端返回的原始有效秒数,读取缓存时应以 ExpiresAt 判断实际到期时间。

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client 提供 QQ 单聊和群聊的鉴权、文本发送及 Webhook 接收能力,不应在创建后复制。

func New

func New(opts ...Option) *Client

New 创建客户端;凭证只保存在内存中,创建时不发起请求或启动后台协程。

func (*Client) GetAccessToken

func (c *Client) GetAccessToken(ctx context.Context) (*AccessTokenResponse, error)

GetAccessToken 返回静态 Token 或缓存凭证,临近过期时按需刷新,不启动后台协程。 并发调用共享成功的刷新结果;返回值是副本,调用方不能修改内部缓存。

func (*Client) SendGroupText

func (c *Client) SendGroupText(ctx context.Context, request SendGroupTextRequest) (*SendTextResponse, error)

SendGroupText 向指定群主动发送或被动回复文本;多次回复同一消息时由调用方递增序号。

func (*Client) SendText

func (c *Client) SendText(ctx context.Context, request SendTextRequest) (*SendTextResponse, error)

SendText 向指定用户主动发送或被动回复文本;MessageSequence 为零时使用协议默认值 1。

func (*Client) WebhookHandler

func (c *Client) WebhookHandler(handler func(context.Context, Message) error) (http.Handler, error)

WebhookHandler 创建可挂载到现有 HTTP 服务的处理器,不启动监听。 每次请求都先验签,消息处理成功返回 d=0,失败返回 d=1 由平台决定重投。 HTTP 请求之间可并发处理,调用方负责回调的并发安全和重复事件去重。

type EventType

type EventType string

EventType 区分 Webhook 推送的消息场景。

const (
	EventC2CMessageCreate     EventType = "C2C_MESSAGE_CREATE"
	EventGroupATMessageCreate EventType = "GROUP_AT_MESSAGE_CREATE"
	EventGroupMessageCreate   EventType = "GROUP_MESSAGE_CREATE"
)

type Message

type Message struct {
	ID          string              `json:"id"`
	Content     string              `json:"content"`
	Timestamp   string              `json:"timestamp"`
	Author      User                `json:"author"`
	GroupID     string              `json:"group_openid,omitempty"`
	Type        int                 `json:"message_type,omitempty"`
	Attachments []MessageAttachment `json:"attachments,omitempty"`
	EventID     string              `json:"-"`
	EventType   EventType           `json:"-"`
	Sequence    uint64              `json:"-"`
}

Message 保留事件内的消息及外层事件标识;ID 与 EventID 分别用于消息回复和事件回复。

type MessageAttachment

type MessageAttachment struct {
	URL         string `json:"url,omitempty"`
	Filename    string `json:"filename,omitempty"`
	ContentType string `json:"content_type,omitempty"`
	Size        int64  `json:"size,omitempty"`
	Width       int    `json:"width,omitempty"`
	Height      int    `json:"height,omitempty"`
}

MessageAttachment 只保留附件元数据,SDK 不下载媒体或发送富媒体消息。

type MessageExtInfo

type MessageExtInfo struct {
	ReferenceIndex string `json:"ref_idx,omitempty"`
}

MessageExtInfo 保存服务端返回的消息引用索引。

type Option

type Option func(*Client)

func WithAppID

func WithAppID(appID string) Option

WithAppID 配置开放平台分配的机器人 AppID。

func WithAppSecret

func WithAppSecret(secret string) Option

WithAppSecret 配置用于获取 Access Token 和 Webhook 验签的机器人密钥。

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL 覆盖消息 API 地址;不改变获取 Token 的固定入口。

func WithClient

func WithClient(cli *restx.Client) Option

WithClient 注入自定义 restx 客户端,用于调整传输配置或本地测试。

func WithInsecureHTTP

func WithInsecureHTTP() Option

WithInsecureHTTP 允许明文消息 API 地址,仅用于可信的开发或测试环境。

func WithSandbox

func WithSandbox() Option

WithSandbox 使用 botgo 定义的沙箱 API 地址,凭证入口仍使用正式环境。

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout 配置一次公开 API 调用的总超时,包括等待和获取 Token 的时间。

func WithToken

func WithToken(token string) Option

WithToken 使用调用方管理的 Access Token,优先于 AppID/AppSecret,SDK 不刷新该 Token。

type SendGroupTextRequest

type SendGroupTextRequest struct {
	GroupID         string
	Text            string
	MessageID       string
	EventID         string
	MessageSequence uint32
}

SendGroupTextRequest 配置群聊文本发送;GroupID 使用入站消息的 group_openid。

type SendTextRequest

type SendTextRequest struct {
	ToUserID        string
	Text            string
	MessageID       string
	EventID         string
	MessageSequence uint32
}

SendTextRequest 配置单聊文本发送;ToUserID 使用入站消息的 author.user_openid。

type SendTextResponse

type SendTextResponse struct {
	MessageID string         `json:"id"`
	Timestamp string         `json:"timestamp"`
	ExtInfo   MessageExtInfo `json:"ext_info,omitempty"`
	TraceID   string         `json:"-"`
}

SendTextResponse 返回服务端消息 ID、发送时间、引用信息及 HTTP 追踪 ID。

type User

type User struct {
	ID           string `json:"id,omitempty"`
	Username     string `json:"username,omitempty"`
	Bot          bool   `json:"bot,omitempty"`
	UserOpenID   string `json:"user_openid,omitempty"`
	MemberOpenID string `json:"member_openid,omitempty"`
	MemberRole   string `json:"member_role,omitempty"`
}

User 的不同 OpenID 只适用于对应场景和当前 AppID,不能跨场景或跨机器人互换。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL