原创 聊天 [1.21.x] 聊天转发API插件 1.0.0

[MD] ### 🎮 插件交流群 [/MD]
点击加入【墨系列插件交流群】

[MD] # ChatForwardPlugin 聊天转发插件 ## 简介 ChatForwardPlugin 是一个 Minecraft 服务器插件，用于将玩家的聊天消息、加入/退出事件、死亡事件等转发到外部 HTTP API。该插件支持 Paper/Spigot 1.21+ 服务器。 可用于对接qq机器人等多种用途。 ## 功能特性 - **聊天消息转发**：实时转发玩家聊天消息到指定 API - **事件消息转发**：支持转发玩家加入、退出、死亡等事件 - **异步处理**：使用异步线程池处理 HTTP 请求，不阻塞主线程 - **自动重试机制**：支持配置重试次数和重试间隔 - **自定义请求头**：支持添加自定义 HTTP 请求头（如认证令牌） - **调试模式**：提供详细的日志输出便于排查问题 - **连接测试**：内置 API 连接测试功能 ## 安装要求 - **服务器核心**：Paper 1.21+ 或 Spigot 1.21+ - **Java版本**：Java 17 或更高版本 - **依赖库**：Gson（已包含在插件中） ## 安装步骤 1. 下载插件 JAR 文件 2. 将 JAR 文件放入服务器的 `plugins` 文件夹 3. 启动服务器，插件会自动生成配置文件 4. 编辑 `plugins/ChatForwardPlugin/config.yml` 配置 API 地址 5. 重启服务器或使用 `/chatforward reload` 重载配置 ## 配置文件 ```yaml # ChatForwardPlugin Configuration # 聊天转发插件配置文件 # API配置 api: # API地址 - 用于转发聊天消息的目标地址 url: "http://localhost:8080/api/chat" # 请求超时时间（毫秒） timeout: 5000 # 重试次数 retry-count: 3 # 重试间隔（毫秒） retry-interval: 1000 # 转发配置 forward: # 是否启用聊天转发 enabled: true # 是否转发玩家加入消息 player-join: false # 是否转发玩家退出消息 player-quit: false # 是否转发玩家死亡消息 player-death: false # 是否转发系统消息 system-messages: false # 调试模式 debug: false # 自定义请求头（可选） headers: # Authorization: "Bearer your-token-here" # X-Custom-Header: "custom-value" ``` ### 配置项说明 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `api.url` | String | `http://localhost:8080/api/chat` | 目标 API 地址 | | `api.timeout` | Integer | 5000 | HTTP 请求超时时间（毫秒） | | `api.retry-count` | Integer | 3 | 请求失败时的重试次数 | | `api.retry-interval` | Integer | 1000 | 重试间隔时间（毫秒） | | `forward.enabled` | Boolean | true | 是否启用聊天转发 | | `forward.player-join` | Boolean | false | 是否转发玩家加入消息 | | `forward.player-quit` | Boolean | false | 是否转发玩家退出消息 | | `forward.player-death` | Boolean | false | 是否转发玩家死亡消息 | | `forward.system-messages` | Boolean | false | 是否转发系统消息 | | `debug` | Boolean | false | 是否启用调试模式 | | `headers` | Map | - | 自定义 HTTP 请求头 | ## 命令 | 命令 | 权限 | 说明 | |------|------|------| | `/chatforward` | `chatforward.admin` | 显示帮助信息 | | `/chatforward reload` | `chatforward.admin` | 重载配置文件 | | `/chatforward status` | `chatforward.admin` | 显示当前状态 | | `/chatforward test` | `chatforward.admin` | 测试 API 连接 | ### 命令别名 - `/cf` - `/chatforward` 的简写形式 ## 权限 | 权限节点 | 默认 | 说明 | |----------|------|------| | `chatforward.admin` | OP | 允许使用所有管理命令 | ## API 数据格式 插件向配置的 API 地址发送 POST 请求，请求体为 JSON 格式： ```json { "player_name": "PlayerName", "player_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "message": "聊天消息内容", "timestamp": 1234567890123, "world": "world", "server_name": "ServerName" } ``` ### 字段说明 | 字段 | 类型 | 说明 | |------|------|------| | `player_name` | String | 玩家名称 | | `player_uuid` | String | 玩家 UUID | | `message` | String | 消息内容 | | `timestamp` | Long | 时间戳（毫秒） | | `world` | String | 玩家所在世界名称 | | `server_name` | String | 服务器名称 | ## 代码架构 ### 核心类说明 | 类名 | 说明 | |------|------| | `ChatForwardPlugin` | 插件主类，负责初始化和生命周期管理 | | `ChatListener` | 事件监听器，监听聊天和玩家事件 | | `HttpForwarder` | HTTP 请求转发器，处理异步 HTTP 请求 | | `ChatMessage` | 聊天消息数据模型 | | `ConfigManager` | 配置管理器，负责加载和读取配置 | | `ChatForwardCommand` | 命令处理器，处理插件命令 | ### 工作流程 1. 玩家发送聊天消息或触发事件 2. `ChatListener` 捕获事件并创建 `ChatMessage` 对象 3. `HttpForwarder` 将消息序列化为 JSON 并发送 HTTP POST 请求 4. 如果请求失败，根据配置进行重试 5. 调试模式下输出详细日志 ## 性能优化 - 使用 `CompletableFuture` 和线程池进行异步处理 - 不阻塞服务器主线程 - 支持连接超时和读取超时配置 - 优雅关闭线程池，避免资源泄漏 ## 故障排查 ### 常见问题 1. **API 连接失败** - 检查 `api.url` 配置是否正确 - 使用 `/chatforward test` 测试连接 - 检查防火墙设置 2. **消息未转发** - 确认 `forward.enabled` 设置为 `true` - 检查玩家是否有发送消息的权限 - 启用 `debug` 模式查看详细日志 3. **性能问题** - 调整 `api.timeout` 避免长时间等待 - 减少 `api.retry-count` 降低重试次数 - 检查目标 API 的响应速度 ### 调试模式 在配置文件中设置 `debug: true` 可以启用调试模式，插件会输出以下信息： - 消息转发成功/失败的详细日志 - HTTP 请求和响应信息 - 重试过程的日志 ## 更新日志 ### v1.0.0 - 初始版本发布 - 支持聊天消息转发 - 支持玩家加入/退出/死亡事件转发 - 支持自定义 HTTP 请求头 - 支持自动重试机制 --- **注意**：请确保目标 API 能够正确处理插件发送的数据格式，并根据需要配置适当的认证机制。 [/MD]