NatsBridge
NatsBridge 是一个 Java 库,可轻松高效地将您的 Spigot、Velocity 或 BungeeCord 插件连接到 NATS 服务器。
? 功能特性
- ✅ 跨插件共享 NATS 连接
- ✅ 支持 Spigot/Paper、Velocity 和 BungeeCord
- ✅ 用于消息处理的高性能 Consumer API
- ✅ 简洁的 API 用于 发布 消息
- ✅ 自动重连 & 错误处理
- ✅ YAML 配置
- ✅ TLS 及认证支持
- ✅ 同步与异步消息处理
? 安装设置
-
下载 JAR 文件:
-
将其放入服务器的 /plugins 文件夹中。
-
启动服务器。将生成一个 nats-config.yml 文件。
-
编辑配置文件并重启服务器。
⚙️ 使用示例
使用高性能 Consumer API
// 同步消费者
NatsAPI api = BungeeCordNatsPlugin.getNatsAPI();
api.subscribeSubject("game.player.join", message -> {
String playerName = new String(message, StandardCharsets.UTF_8);
System.out.println("玩家加入: " + playerName);
}, false);
// 异步消费者 (byte[])
api.subscribeSubject("game.chat", message -> {
// 异步处理聊天消息
String chatMessage = new String(message, StandardCharsets.UTF_8);
broadcastToAllServers(chatMessage);
}, true);
// 异步消费者 (String) - 更方便!
api.subscribeStringSubject("game.chat", chatMessage -> {
// 直接接收为 String - 无需手动转换
broadcastToAllServers(chatMessage);
}, true);
发布消息
首先,您需要知道连接何时建立。
Velocity、Bungeecord 和 Spigot 分别有 3 个对应的事件。
- VelocityNatsBridgeConnectedEvent
- BungeeNatsBridgeConnectedEvent
- SpigotNatsBridgeConnectedEvent
类似如下代码:
@EventHandler
public void onNatsBridgeConnected(SpigotNatsBridgeConnectedEvent event) {
//在此处执行操作
}
您只需监听这些事件,当与 NATS 的连接建立时,该事件将被触发。
BungeeCordNatsPlugin.getNatsAPI().publishString("subject", "Awesome message");
BungeeCordNatsPlugin.getNatsAPI().publishRaw("subject", [something that is byte[]]);
? 配置 (nats-config.yml)
nats:
# NATS 服务器列表(可以是单台服务器或集群)
servers:
- "nats://127.0.0.1:4222"
- "nats://nats-cluster.local:4222"
# 认证配置(可选)
auth:
enabled: true
# 用户名/密码认证
username: "user"
password: "pass"
# 或者令牌认证(如果提供,用户名/密码将被忽略)
# token: "your_token_here"
# TLS 配置(可选)
tls:
enabled: false
# 密钥库路径(可选)
# keystore: "/path/to/keystore.jks"
# keystore_password: "keystore_password"
# 信任库路径(可选)
# truststore: "/path/to/truststore.jks"
# truststore_password: "truststore_password"
# 重连配置
reconnect:
# 最大重连尝试次数 (-1 = 无限次)
max_reconnects: -1
# 重连尝试之间的延迟(毫秒)
reconnect_wait: 2000
# 连接超时时间(毫秒)
connection_timeout: 5000
? 命令
/nats help – 显示帮助菜单
/nats status – 检查 NATS 连接状态
/nats test <subject> <message> – 发送测试消息
/nats reload – 重新加载 NATS 配置(计划中)
所需权限:natsbridge.admin
? Gradle
repositories {
maven {
name = "natsbridge-repo"
url = uri("https://repo.nhsoul.fr/releases")
}
}
dependencies {
//使用最新版本
// 必需依赖
compileOnly("fr.nhsoul.natsbridge:core:1.0.0")
compileOnly("fr.nhsoul.natsbridge:common:1.0.0")
//选择您的平台
compileOnly("fr.nhsoul.natsbridge:spigot:1.0.0")
compileOnly("fr.nhsoul.natsbridge:velocity:1.0.0")
compileOnly("fr.nhsoul.natsbridge:bungeecord:1.0.0")
}
? 性能考量
Consumer API 方法具有多项优势:
- 无反射开销:原生性能的消息处理。
- 类型安全:使用标准 Java 接口。
- 显式控制:您可以精确控制消息处理的时机和方式。
- 平台集成:轻松访问平台特定的 API(Spigot、Velocity、BungeeCord)。
✅ 环境要求
- Java 21+
- 一台 NATS 服务器
- Minecraft 1.20+ 服务器(Spigot、Velocity 或 BungeeCord)
? 贡献指南
- Fork 本仓库
- 创建分支
- 提交 PR —— 欢迎所有贡献!
NatsBridge
NatsBridge is a Java library that connects your Spigot, Velocity, or BungeeCord plugins to a NATS server — easily and efficiently.
? Features
- ✅ Shared NATS connection across plugins
- ✅ Supports Spigot/Paper, Velocity, and BungeeCord
- ✅ High-performance Consumer API for message handling
- ✅ Clean API to publish messages
- ✅ Auto-reconnect & error handling
- ✅ YAML configuration
- ✅ TLS & authentication support
- ✅ Sync & async message handling
? Setup
-
Download the JAR:
-
Drop it into your server’s /plugins folder.
-
Start the server. A nats-config.yml file will be generated.
-
Edit the config file and restart.
⚙️ Usage Example
Using high-performance Consumer API
// Sync consumer
NatsAPI api = BungeeCordNatsPlugin.getNatsAPI();
api.subscribeSubject("game.player.join", message -> {
String playerName = new String(message, StandardCharsets.UTF_8);
System.out.println("Player joined: " + playerName);
}, false);
// Async consumer (byte[])
api.subscribeSubject("game.chat", message -> {
// Process chat message asynchronously
String chatMessage = new String(message, StandardCharsets.UTF_8);
broadcastToAllServers(chatMessage);
}, true);
// Async consumer (String) - more convenient!
api.subscribeStringSubject("game.chat", chatMessage -> {
// Directly receive as String - no need for manual conversion
broadcastToAllServers(chatMessage);
}, true);
Publish a message
Firstly you need to know when the connection is established.
There are 3 events for Velocity, Bungeecord and Spigot.
- VelocityNatsBridgeConnectedEvent
- BungeeNatsBridgeConnectedEvent
- SpigotNatsBridgeConnectedEvent
Something like
@EventHandler
public void onNatsBridgeConnected(SpigotNatsBridgeConnectedEvent event) {
//Do something here
}
You just need to listen these events and the event is fire when the connection to NATS is up.
BungeeCordNatsPlugin.getNatsAPI().publishString("subject", "Awesome message");
BungeeCordNatsPlugin.getNatsAPI().publishRaw("subject", [something that is byte[]]);
? Configuration (nats-config.yml)
nats:
# List of NATS servers (can be a single server or a cluster)
servers:
- "nats://127.0.0.1:4222"
- "nats://nats-cluster.local:4222"
# Authentication configuration (optional)
auth:
enabled: true
# Username/password authentication
username: "user"
password: "pass"
# OR token authentication (if provided, username/password are ignored)
# token: "your_token_here"
# TLS configuration (optional)
tls:
enabled: false
# Paths to keystores (optional)
# keystore: "/path/to/keystore.jks"
# keystore_password: "keystore_password"
# truststore: "/path/to/truststore.jks"
# truststore_password: "truststore_password"
# Reconnection configuration
reconnect:
# Maximum number of reconnection attempts (-1 = unlimited)
max_reconnects: -1
# Delay between reconnection attempts (in milliseconds)
reconnect_wait: 2000
# Connection timeout (in milliseconds)
connection_timeout: 5000
? Commands
/nats help – Show help menu
/nats status – Check NATS connection status
/nats test <subject> <message> – Send a test message
/nats reload – Reload NATS configuration (planned)
Permission required: natsbridge.admin
? Gradle
repositories {
maven {
name = "natsbridge-repo"
url = uri("https://repo.nhsoul.fr/releases")
}
}
dependencies {
//Use the latest version
// Mandatory
compileOnly("fr.nhsoul.natsbridge:core:1.0.0")
compileOnly("fr.nhsoul.natsbridge:common:1.0.0")
//Select your platform
compileOnly("fr.nhsoul.natsbridge:spigot:1.0.0")
compileOnly("fr.nhsoul.natsbridge:velocity:1.0.0")
compileOnly("fr.nhsoul.natsbridge:bungeecord:1.0.0")
}
? Performance Considerations
The Consumer API approach offers several advantages:
- No reflection overhead: Native performance for message handling.
- Type safety: Use of standard Java interfaces.
- Explicit control: You control exactly when and how messages are processed.
- Platform integration: Easy access to platform-specific APIs (Spigot, Velocity, BungeeCord).
✅ Requirements
- Java 21+
- A NATS server
- Minecraft 1.20+ server (Spigot, Velocity, or BungeeCord)
? Contributing
- Fork this repo
- Create a branch
- Submit a PR – all contributions welcome!
评论 0
登录后参与评分
还没有评论,来抢沙发吧