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

Java Server SDK

XuqmGroup 服务端 Java SDK，封装了以下能力：

• IM 账号、UserSig 生成与登录
• 消息发送、编辑、撤回、历史查询
• 好友、黑名单、会话、群组
• Webhook、管理端操作
• Push 注册与发送

---

安装

Maven 在 pom.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：

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

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

---

初始化

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 绝不下发到客户端。

---

UserSig

String userSig = client.generateUserSig("user_001");
boolean valid = client.verifyUserSig("user_001", userSig);
var login = client.loginWithUserSig("user_001", userSig);

管理员账号可用于服务端 SDK / 管理端 REST API；建议在 IM 管理页先给对应注册用户打上管理员标记。

---

发送消息

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());

发送群消息

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

撤回消息

client.revokeMessage("message_id");

---

能力分类

分类	主要方法
IM 账号	generateUserSig, verifyUserSig, login, loginWithUserSig, 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, pushUserStatus, pushDeviceLogs, testOfflinePush

群管理示例

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

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

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

---

错误处理

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 文档