Skip to content

README_zh.md

Latest commit

 

History

History
128 lines (91 loc) · 4.47 KB

README_zh.md

File metadata and controls

128 lines (91 loc) · 4.47 KB
Raw

JuggleIM 服务端 Java SDK

面向 JuggleIM REST API 的服务端 Java 客户端。

License CI Java Stars

English · 简体中文

官网 · 文档 · 服务端 API · IM Server

imserver-sdk-java 帮助可信任的 Java 业务后端调用 JuggleIM 服务端 API，无需重复实现请求签名和响应映射。它仅用于服务端；App Secret 绝不能嵌入 Android、桌面、Web 或其他客户端应用。

API 覆盖

  • 用户：注册、查询、更新、踢出、在线状态、封禁、黑名单和标签
  • 消息：单聊消息、聊天室消息、聊天室广播和撤回
  • 群组：创建、更新、解散、查询、成员管理、禁言、白名单和设置
  • 聊天室：创建、销毁、查询、成员检查、封禁和禁言控制
  • 敏感词：添加、删除、查询和文件导入

需要更广的 API 覆盖时，也可以查看 Go 和 Python 服务端 SDK。

环境要求

  • JDK 23 或更高版本（与当前 pom.xml 编译目标一致）
  • Maven 3.8+
  • 正在运行的 JuggleIM 服务
  • 通过 JuggleIM 管理控制台创建的 App Key 和 App Secret

从源码安装

当前构件尚未发布到 Maven Central，请先构建并安装到本地 Maven 仓库：

git clone https://github.com/juggleim/imserver-sdk-java.git
cd imserver-sdk-java
mvn clean install

然后在 Maven 项目中添加：

<dependency>
  <groupId>com.juggle.im</groupId>
  <artifactId>imserver-sdk-java</artifactId>
  <version>1.1</version>
</dependency>

快速开始

import com.juggle.im.JuggleIm;
import com.juggle.im.models.user.UserInfo;
import com.juggle.im.models.user.UserTokenResult;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        JuggleIm sdk = new JuggleIm(
                System.getenv("JUGGLEIM_APP_KEY"),
                System.getenv("JUGGLEIM_APP_SECRET"),
                System.getenv().getOrDefault("JUGGLEIM_API_URL", "http://127.0.0.1:9001")
        );

        UserInfo user = new UserInfo()
                .setUserId("user-001")
                .setNickname("Demo User")
                .setUserPortrait("https://example.com/avatar.png");

        UserTokenResult result = sdk.user.register(user);
        System.out.println(result);
    }
}

通过环境变量运行示例，不要把凭据提交到仓库：

export JUGGLEIM_APP_KEY="your-app-key"
export JUGGLEIM_APP_SECRET="your-app-secret"
export JUGGLEIM_API_URL="http://127.0.0.1:9001"

mvn package

然后在 IDE 中使用 Maven 项目 Classpath 运行 com.juggle.im.example.user.UserExample。 生成的 JAR 不是包含全部依赖的 uber-JAR，运行时仍需保留 SDK 的 Maven 依赖。

示例程序会调用真实的 JuggleIM 服务。对非开发环境执行前，请先检查示例中的用户 ID 和请求数据。

开发

mvn test
mvn package

源码位于 src/main/java/com/juggle/im/。主要入口是 com.juggle.im.JuggleIm，它提供 user、msgSender、group、chatroom 和 sensitiveWord API 分组。

安全说明

  • App Secret 只应保存在可信任的服务端基础设施中。
  • 使用环境变量或密钥管理服务加载凭据。
  • 生产环境 API 流量必须使用 HTTPS。
  • 不要在示例或测试中提交生产用户 ID、Token、消息内容或任何凭据。
  • 安全漏洞请通过仓库 Security 页面私下报告。

参与贡献

欢迎提交 Issue 和 Pull Request。新增接口时，请同时提供请求/响应模型、示例或单元测试，并附上对应的服务端 API 链接。

许可证

Apache License 2.0