XuqmGroup-Web/docs-site/docs/server/go-sdk.md

Go Server SDK

XuqmGroup 服务端 Go SDK，封装了：

• IM 账号、UserSig 生成与登录、消息、群组、好友、会话、黑名单
• 管理端 Webhook、操作日志
• Push 注册与推送

---

安装

go get github.com/xuqmgroup/xuqmgroup-server-sdk-go

---

初始化

import xuqmsdk "github.com/xuqmgroup/xuqmgroup-server-sdk-go"

client, err := xuqmsdk.NewClient(xuqmsdk.ClientConfig{
    BaseURL:   "https://dev.xuqinmin.com",
    AppKey:    "your_app_key",
    AppSecret: "your_app_secret",
})
if err != nil {
    log.Fatal(err)
}

服务端 SDK 需要 appSecret 用于 HMAC 签名，appSecret 绝不下发到客户端。

---

UserSig

userSig := client.GenerateUserSig("user_001")
valid := client.VerifyUserSig("user_001", userSig)
login, err := client.LoginWithUserSig("user_001", userSig)

管理员账号可用于服务端 SDK / 管理端 REST API。

---

能力分类

分类	主要方法
登录	GenerateUserSig, VerifyUserSig, Login, LoginWithUserSig
账号	ImportAccount, ImportAccounts, DeleteAccount, GetProfile, UpdateProfile, SearchAccounts, CheckAccount
消息	SendMessage, RevokeMessage, EditMessage, FetchHistory, FetchGroupHistory, SearchMessages
会话	ListConversations, SetConversationPinned, SetConversationMuted, MarkRead, SetDraft, SetConversationHidden, SetConversationGroup, DeleteConversation
好友	ListFriends, AddFriend, AddFriends, RemoveFriend, RemoveFriends, RemoveAllFriends, SetFriendGroup, ListFriendGroups, ListFriendsByGroup, CheckFriends
黑名单	ListBlacklist, AddBlacklist, RemoveBlacklist, CheckBlacklist
群组	ListGroups, ListPublicGroups, SearchGroups, GetGroup, ListGroupMembers, SearchGroupMembers, CreateGroup, UpdateGroup, AddGroupMember, AddGroupMembers, RemoveGroupMember, RemoveGroupMembers, SetGroupRole, TransferGroupOwner, LeaveGroup, UpdateGroupAttributes, RemoveGroupAttributes, MuteGroupMember, DismissGroup, SendGroupJoinRequest, ListGroupJoinRequests, AcceptGroupJoinRequest, RejectGroupJoinRequest, AcceptGroupJoinRequests, RejectGroupJoinRequests
管理端	QueryUserState, KickUsers, BatchSendMessage, AdminSetMsgRead, ImportMessages, AdminTransferGroupOwner, AdminUpdateGroupAttributes, AdminRemoveGroupAttributes, AdminGroupReadReceipts
Webhook	ListWebhooks, CreateWebhook, UpdateWebhook, DeleteWebhook, VerifyCallbackSignature, ParseCallbackEnvelope
Push	RegisterPushToken, SendPush, PushUserStatus, PushDeviceLogs, TestOfflinePush

---

发送消息

msg, err := client.SendMessage(xuqmsdk.SendMessageRequest{
    ToID:     "user_002",
    ChatType: "SINGLE",
    MsgType:  "TEXT",
    Content:  "Hello from Go SDK!",
})
if err != nil {
    log.Fatal(err)
}
log.Printf("消息已发送: %s", msg.ID)

发送群消息

msg, err := client.SendMessage(xuqmsdk.SendMessageRequest{
    ToID:     "group_xxx",
    ChatType: "GROUP",
    MsgType:  "TEXT",
    Content:  "大家好",
})

撤回消息

err := client.RevokeMessage("message_id")

---

群管理

group, err := client.CreateGroup("项目讨论", []string{"user_001", "user_002"}, "NORMAL")
if err != nil {
    log.Fatal(err)
}

err = client.AddGroupMember("group_xxx", "user_003")
err = client.RemoveGroupMember("group_xxx", "user_003")

groups, err := client.ListGroups()
members, err := client.ListGroupMembers("group_xxx")

---

Push 推送

err := client.SendPush("user_001", "新消息", "你有一条未读消息", `{"chatId":"user_002"}`)

---

错误处理

SDK 返回的错误实现了标准 error 接口。业务方可根据错误类型做不同处理：

msg, err := client.SendMessage(req)
if err != nil {
    if apiErr, ok := err.(*xuqmsdk.APIError); ok {
        log.Printf("API 错误: status=%d, code=%d, message=%s", apiErr.Status, apiErr.Code, apiErr.Message)
    }
}

→ Server API 文档