anna/IM-server-new
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

添加server sdk readme

Browse Source
This commit is contained in:
heavyrian2012
2026-03-15 10:30:00 +08:00
parent be5a24a6fd
commit 3eef24bdb9
1 changed files with 359 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
sdk/README.md
+359
View File
@@ -0,0 +1,359 @@
# 野火IM Server Java SDK
野火IM Server Java SDK 是野火IM服务器的官方 Java 语言 SDK，提供了完整的 Admin API、Robot API 和 Channel API 接口封装。
## 功能特性
- **用户管理**：创建用户、获取用户信息、更新用户信息、封禁/解封用户等
- **群组管理**：创建群组、添加/移除成员、转让群主、设置管理员等
- **消息管理**：发送消息、广播消息、撤回消息、删除消息等
- **好友关系**：添加好友、删除好友、获取好友列表、设置黑名单等
- **聊天室管理**：创建聊天室、获取聊天室信息、销毁聊天室等
- **频道管理**：创建频道、订阅/取消订阅、发送频道消息等
- **机器人服务**：机器人消息收发、用户信息查询、群组管理等
- **会议管理**：创建会议、查询会议信息、管理参会者等（高级音视频功能）
- **朋友圈功能**：发布动态、评论、点赞等（需启用朋友圈功能）
- **敏感词管理**：添加/删除敏感词、检查敏感词等
## 安装
### Maven 依赖
```xml
<dependencies>
<!-- 必需依赖 -->
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.9</version>
</dependency>
<dependency>
<groupId>commons-httpclient</groupId>
<artifactId>commons-httpclient</artifactId>
<version>3.1</version>
</dependency>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
<version>4.5.13</version>
</dependency>
<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.15</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>com.googlecode.json-simple</groupId>
<artifactId>json-simple</artifactId>
<version>1.1.1</version>
</dependency>
<!-- SDK JAR (本地路径根据实际情况修改) -->
<dependency>
<groupId>cn.wildfirechat</groupId>
<artifactId>sdk</artifactId>
<version>1.2.2</version>
<scope>system</scope>
<systemPath>${project.basedir}/lib/sdk.jar</systemPath>
</dependency>
<dependency>
<groupId>cn.wildfirechat</groupId>
<artifactId>common</artifactId>
<version>1.2.2</version>
<scope>system</scope>
<systemPath>${project.basedir}/lib/common.jar</systemPath>
</dependency>
</dependencies>
<!-- Spring Boot 项目需要添加 includeSystemScope -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<includeSystemScope>true</includeSystemScope>
</configuration>
</plugin>
</plugins>
</build>
```
### SDK 获取
1. 从源码编译：本项目位于 `server/sdk` 目录
2. 从发布包获取：在 release 包的 `server_sdk` 目录中
## 快速开始
### Admin 管理 API
```java
import cn.wildfirechat.sdk.AdminConfig;
import cn.wildfirechat.sdk.UserAdmin;
import cn.wildfirechat.sdk.MessageAdmin;
import cn.wildfirechat.pojos.InputOutputUserInfo;
import cn.wildfirechat.pojos.Conversation;
import cn.wildfirechat.sdk.messagecontent.TextMessageContent;
import cn.wildfirechat.proto.ProtoConstants;
import cn.wildfirechat.sdk.model.IMResult;
public class QuickStart {
public static void main(String[] args) throws Exception {
// 初始化配置
AdminConfig.initAdmin("http://localhost:18080", "123456");
// 创建用户
InputOutputUserInfo user = new InputOutputUserInfo();
user.setUserId("user1");
user.setName("user1");
user.setDisplayName("Test User");
user.setMobile("13900000000");
IMResult<OutputCreateUser> result = UserAdmin.createUser(user);
if (result.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("创建用户成功: " + result.getResult().getUserId());
}
// 获取用户 Token
IMResult<OutputGetIMTokenData> tokenResult = UserAdmin.getUserToken(
"user1",
"client1",
ProtoConstants.Platform.Platform_Android
);
if (tokenResult.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("Token: " + tokenResult.getResult().getToken());
}
// 发送消息
Conversation conversation = new Conversation();
conversation.setType(ProtoConstants.ConversationType.ConversationType_Private);
conversation.setTarget("user2");
conversation.setLine(0);
TextMessageContent content = new TextMessageContent("Hello, World!");
MessagePayload payload = content.encode();
IMResult<SendMessageResult> msgResult = MessageAdmin.sendMessage("user1", conversation, payload);
if (msgResult.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("消息发送成功，ID: " + msgResult.getResult().getMessageUid());
}
}
}
```
### Robot 机器人服务
```java
import cn.wildfirechat.sdk.RobotService;
import cn.wildfirechat.sdk.messagecontent.TextMessageContent;
public class RobotExample {
public static void main(String[] args) throws Exception {
// 初始化机器人服务
RobotService robot = new RobotService("http://localhost", "robot1", "123456");
// 获取机器人信息
IMResult<OutputRobot> profile = robot.getProfile();
if (profile.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("机器人名称: " + profile.getResult().getDisplayName());
}
// 发送消息给用户
TextMessageContent content = new TextMessageContent("Hello from robot!");
IMResult<SendMessageResult> result = robot.sendMessage("user1", content);
if (result.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("机器人消息发送成功");
}
// 获取用户信息
IMResult<OutputUserInfo> userInfo = robot.getUserInfo("user1");
if (userInfo.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("用户显示名: " + userInfo.getResult().getDisplayName());
}
}
}
```
### Channel 频道服务
```java
import cn.wildfirechat.sdk.ChannelServiceApi;
import cn.wildfirechat.sdk.messagecontent.TextMessageContent;
public class ChannelExample {
public static void main(String[] args) throws Exception {
// 初始化频道服务
ChannelServiceApi channel = new ChannelServiceApi("http://localhost", "channel1", "secret");
// 发送广播消息给订阅者
TextMessageContent content = new TextMessageContent("Channel broadcast message");
IMResult<SendMessageResult> result = channel.broadcastMessage(content);
if (result.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("频道广播消息发送成功");
}
// 用户订阅频道
IMResult<Void> subscribeResult = channel.subscribe("user1");
if (subscribeResult.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("订阅成功");
}
// 获取频道订阅者（商业版功能）
IMResult<OutputStringList> subscribers = channel.getSubscriberList();
if (subscribers.getErrorCode() == ErrorCode.ERROR_CODE_SUCCESS) {
System.out.println("订阅者数量: " + subscribers.getResult().getList().size());
}
}
}
```
## 运行测试
SDK 提供了完整的测试示例 `Main.java`：
```bash
# 编译
mvn compile
# 运行测试（使用默认配置）
mvn exec:java -Dexec.mainClass="cn.wildfirechat.sdk.Main"
# 运行测试（自定义配置）
mvn exec:java -Dexec.mainClass="cn.wildfirechat.sdk.Main" \
-Dexec.args="http://your-server:18080 your-secret http://your-server false false"
```
### 命令行参数
```
Usage: java -jar sdk.jar adminUrl adminSecret imUrl commercialServer advanceVoip
参数说明:
adminUrl - 管理API地址，如 http://localhost:18080
adminSecret - 管理员密钥
imUrl - IM服务地址（机器人/频道使用），如 http://localhost
commercialServer - 是否为商业版服务器 (true/false)
advanceVoip - 是否启用高级音视频功能 (true/false)
```
## 项目结构
```
sdk/
├── src/main/java/cn/wildfirechat/
│ ├── sdk/
│ │ ├── AdminConfig.java # 配置类
│ │ ├── UserAdmin.java # 用户管理
│ │ ├── GroupAdmin.java # 群组管理
│ │ ├── MessageAdmin.java # 消息管理
│ │ ├── RelationAdmin.java # 好友关系管理
│ │ ├── ChatroomAdmin.java # 聊天室管理
│ │ ├── ChannelAdmin.java # 频道管理
│ │ ├── GeneralAdmin.java # 通用管理
│ │ ├── SensitiveAdmin.java # 敏感词管理
│ │ ├── ConferenceAdmin.java # 会议管理
│ │ ├── MomentsAdmin.java # 朋友圈管理
│ │ ├── RobotService.java # 机器人服务
│ │ ├── ChannelServiceApi.java # 频道服务API
│ │ ├── MeshAdmin.java # Mesh分布式管理
│ │ └── Main.java # 测试主程序
│ │ └── messagecontent/ # 消息内容类
│ │ ├── MessageContent.java
│ │ ├── TextMessageContent.java
│ │ ├── ImageMessageContent.java
│ │ ├── SoundMessageContent.java
│ │ ├── VideoMessageContent.java
│ │ ├── FileMessageContent.java
│ │ └── ...
│ ├── common/ # 公共模块（依赖）
│ └── proto/ # 协议常量
└── pom.xml # Maven配置
```
## 主要 API 说明
### 用户管理 (UserAdmin)
| 方法 | 说明 |
|------|------|
| `createUser()` | 创建用户 |
| `getUserByName()` | 按用户名获取用户 |
| `getUserByMobile()` | 按手机号获取用户 |
| `getUserByUserId()` | 按用户ID获取用户 |
| `updateUserInfo()` | 更新用户信息 |
| `getUserToken()` | 获取用户IM Token |
| `updateUserBlockStatus()` | 封禁/解封用户 |
| `checkUserOnlineStatus()` | 检查用户在线状态 |
### 群组管理 (GroupAdmin)
| 方法 | 说明 |
|------|------|
| `createGroup()` | 创建群组 |
| `getGroupInfo()` | 获取群组信息 |
| `addGroupMembers()` | 添加群成员 |
| `kickoffGroupMembers()` | 踢出群成员 |
| `transferGroup()` | 转让群主 |
| `dismissGroup()` | 解散群组 |
### 消息管理 (MessageAdmin)
| 方法 | 说明 |
|------|------|
| `sendMessage()` | 发送消息 |
| `broadcastMessage()` | 广播消息 |
| `multicastMessage()` | 群发消息 |
| `recallMessage()` | 撤回消息 |
| `deleteMessage()` | 删除消息 |
### 好友关系 (RelationAdmin)
| 方法 | 说明 |
|------|------|
| `setUserFriend()` | 设置好友关系 |
| `getFriendList()` | 获取好友列表 |
| `setUserBlacklist()` | 设置黑名单 |
| `getUserBlacklist()` | 获取黑名单列表 |
## 接口文档
- [Admin API 文档](https://docs.wildfirechat.cn/server/admin_api/) - 服务端管理接口，包括用户、群组、消息、频道等管理功能
- [Robot API 文档](https://docs.wildfirechat.cn/server/robot_api/) - 机器人服务接口，用于开发机器人应用
- [Channel API 文档](https://docs.wildfirechat.cn/server/channel_api/) - 频道服务接口，用于开发公众号/频道应用
- [IM 开发文档](https://docs.wildfirechat.cn/) - 野火IM完整开发文档
## 其他语言 SDK
| 语言 | GitHub | Gitee(码云) |
|------|------------------------------------------------------------------|-------------|
| Java SDK | [GitHub](https://github.com/wildfirechat/server/tree/master/sdk) | [Gitee](https://gitee.com/wfchat/im-server/tree/wildfirechat/sdk) |
| Python SDK | [GitHub](https://github.com/wildfirechat/server-sdk-python) | [Gitee](https://gitee.com/wfchat/im-server/server-sdk-python) |
| Go SDK | [GitHub](https://github.com/wildfirechat/server-sdk-go) | [Gitee](https://gitee.com/wfchat/server-sdk-go) |
| Node.js SDK | [GitHub](https://github.com/wildfirechat/server-sdk.js) | [Gitee](https://gitee.com/wfchat/server-sdk.js) |
## 相关链接
- [野火IM 官网](https://wildfirechat.cn/)
- [在线文档](https://docs.wildfirechat.cn/)
- [服务端源码 - GitHub](https://github.com/wildfirechat/server) | [Gitee](https://gitee.com/wfchat/im-server)
- [应用服务源码 - GitHub](https://github.com/wildfirechat/app-server) | [Gitee](https://gitee.com/wfchat/app-server)
- [机器人服务源码 - GitHub](https://github.com/wildfirechat/robot-server) | [Gitee](https://gitee.com/wfchat/robot-server)
- [推送服务源码 - GitHub](https://github.com/wildfirechat/push-server) | [Gitee](https://gitee.com/wfchat/push-server)
- [论坛交流](https://bbs.wildfirechat.cn/)
## 注意事项
1. **Admin API** 使用 18080 端口，具有超级管理权限，理论上不应对外开放，也不应让非内部服务知悉密钥。
2. **Robot API** 和 **Channel API** 使用 IM 服务的公开端口（默认 80），第三方可以使用机器人或频道与 IM 系统进行对接。
3. 商业版服务器支持更多高级功能，如在线用户统计、设备管理等。
4. 高级音视频功能需要单独启用，支持会议管理相关 API。
## 许可证
本项目采用与野火IM相同的许可证。