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

# Java Server SDK

XuqmGroup 服务端 Java SDK，按腾讯云服务端 API 的思路封装了以下能力：

- IM 账号与登录
- 消息发送、编辑、撤回、历史查询
- 好友、黑名单、会话、群组
- Webhook、管理端操作、统计
- Push 注册与发送
- Update 版本检查、上传、发布、灰度、应用商店提审

---

## 安装

Maven 在 `pom.xml` 中添加：

```xml
<repository>
  <id>xuqm-nexus</id>
  <url>https://nexus.xuqinmin.com/repository/maven-public/</url>
</repository>

<dependency>
  <groupId>com.xuqm</groupId>
  <artifactId>im-sdk</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>
```

Gradle：

```kotlin
repositories {
    maven { url = uri("https://nexus.xuqinmin.com/repository/maven-public/") }
}

dependencies {
    implementation("com.xuqm:im-sdk:0.1.0-SNAPSHOT")
}
```

---

## 初始化

```java
import com.xuqm.im.sdk.XuqmImServerSdk;

XuqmImServerSdk client = XuqmImServerSdk.builder()
    .baseUrl("https://dev.xuqinmin.com")
    .appKey("your_app_key")
    .appSecret("your_app_secret")
    .build();
```

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

---

## 发送消息

```java
import com.xuqm.im.sdk.XuqmImServerSdk.ImMessage;
import com.xuqm.im.sdk.XuqmImServerSdk.SendMessageRequest;

ImMessage msg = client.sendMessage(new SendMessageRequest(
    "user_002",
    "SINGLE",
    "TEXT",
    "Hello from Java SDK!",
    null,
    null,
    null
));

System.out.println("消息已发送: " + msg.getId());
```

### 发送群消息

```java
ImMessage msg = client.sendMessage(SendMessageRequest.builder()
    .toId("group_xxx")
    .chatType("GROUP")
    .msgType("TEXT")
    .content("大家好")
    .build());
```

### 撤回消息

```java
client.revokeMessage("message_id");
```

---

## 能力分类

| 分类 | 主要方法 |
|------|----------|
| IM 账号 | `login`, `importAccount`, `importAccounts`, `deleteAccount`, `getProfile`, `updateProfile`, `searchAccounts` |
| 消息 | `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`, `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`, 各类 `parse*CallbackPayload` |
| Push | `registerPushToken`, `sendPush` |
| Update | `checkAppUpdate`, `uploadAppVersion`, `publishAppVersion`, `unpublishAppVersion`, `grayAppVersion`, `listAppVersions`, `checkRnUpdate`, `uploadRnBundle`, `publishRnBundle`, `unpublishRnBundle`, `listRnBundles` |

## 群管理示例

```java
import com.xuqm.im.sdk.XuqmImServerSdk.GroupView;

GroupView group = client.createGroup("项目讨论", List.of("user_001", "user_002"), "NORMAL");

client.addGroupMember("group_xxx", "user_003");
client.removeGroupMember("group_xxx", "user_003");

List<GroupView> groups = client.listGroups();
```

---

## Push 推送

```java
import com.xuqm.sdk.server.model.SendPushRequest;

client.sendPush(SendPushRequest.builder()
    .userId("user_001")
    .title("新消息")
    .body("你有一条未读消息")
    .payload("{\"chatId\":\"user_002\"}")
    .build());
```

---

## 错误处理

```java
import com.xuqm.im.sdk.XuqmImServerSdk.ImSdkException;

try {
    ImMessage msg = client.sendMessage(request);
} catch (ImSdkException e) {
    System.err.printf("API 错误: status=%d, code=%d, message=%s%n",
        e.getHttpStatus(), e.getCode(), e.getMessage());
}
```

[→ Server API 文档](/server/api)