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

# Go Server SDK

XuqmGroup 服务端 Go SDK，封装了：

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

---

## 安装

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

---

## 初始化

```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

```go
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` |

---

## 发送消息

```go
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)
```

### 发送群消息

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

### 撤回消息

```go
err := client.RevokeMessage("message_id")
```

---

## 群管理

```go
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 推送

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

---

## 错误处理

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

```go
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 文档](/server/api)