# imserver-sdk-java

**Repository Path**: juggleim/imserver-sdk-java

## Basic Information

- **Project Name**: imserver-sdk-java
- **Description**: Java 语言版本的 JuggleIM API SDK
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-10-17
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# JuggleIM 服务端 Java SDK

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

[![License](https://img.shields.io/github/license/juggleim/imserver-sdk-java?style=flat-square)](./LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/juggleim/imserver-sdk-java/ci.yml?branch=master&style=flat-square&label=CI)](https://github.com/juggleim/imserver-sdk-java/actions/workflows/ci.yml)
[![Java](https://img.shields.io/badge/Java-23+-f89820?style=flat-square&logo=openjdk)](./pom.xml)
[![Stars](https://img.shields.io/github/stars/juggleim/imserver-sdk-java?style=flat-square)](https://github.com/juggleim/imserver-sdk-java/stargazers)

**[English](./README.md)** · **简体中文**

[官网](https://www.juggle.im/) ·
[文档](https://www.juggle.im/docs/guide/intro/) ·
[服务端 API](https://www.juggle.im/docs/server/api/) ·
[IM Server](https://github.com/juggleim/im-server)

</div>

---

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

## API 覆盖

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

需要更广的 API 覆盖时，也可以查看 [Go](https://github.com/juggleim/imserver-sdk-go) 和
[Python](https://github.com/juggleim/imserver-sdk-python) 服务端 SDK。

## 环境要求

- JDK 23 或更高版本（与当前 `pom.xml` 编译目标一致）
- Maven 3.8+
- 正在运行的 [JuggleIM 服务](https://github.com/juggleim/im-server)
- 通过 JuggleIM 管理控制台创建的 App Key 和 App Secret

## 从源码安装

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

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

然后在 Maven 项目中添加：

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

## 快速开始

```java
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);
    }
}
```

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

```bash
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 和请求数据。

## 开发

```bash
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](https://www.juggle.im/docs/server/api/) 链接。

## 许可证

[Apache License 2.0](./LICENSE)