? Server Info API Mod
通过 HTTP API 访问和扩展服务器信息
本模组旨在为 Minecraft 服务器所有者和模组开发者提供强大且易于扩展的 HTTP API。获取实时服务器统计数据,并将您的服务器和模组数据无缝集成到外部应用程序或 Web 界面中。
✨ 为什么您需要这个模组
您是否正在寻找:
- ? 通过 HTTP 请求监控您的服务器?
- ? 在网站上显示实时玩家数量?
- ? 创建与您的服务器数据交互的自定义 Discord 机器人?
- ? 允许其他模组轻松通过统一 API 暴露其数据?
Server Info API 模组让这一切变得更加简单!它为 Minecraft 服务器设置了一个专用的 API 端点,既提供基本的预定义路由,也为开发者提供了灵活的系统以添加自己的路由。
⚙️ 快速设置
默认情况下,API 运行在端口 8080 上。您可以通过修改 config/Server Info API/settings.json 中的 apiPort 设置来轻松更改此端口以适应您的需求。
? API 端点 - 您可以访问的内容
本模组附带强大的预定义路由,让您立即开始使用。
? /status
获取服务器关键统计信息的全面概览,包括磁盘使用情况、CPU 负载、RAM 消耗以及当前在线玩家数量。
示例响应:
{
"disk": {
"totalGB": 1606,
"freeGB": 343,
"usedMB": 25
},
"players": {
"online": 0,
"max": 20
},
"cpu": {
"usagePercent": 9.865470852017937
},
"ram": {
"totalMB": 63033,
"usedMB": 31469
}
}
? /players
显示曾经加入过您服务器的玩家总数,并查看所有当前在线玩家的列表。
示例响应:
{
"totalPlayers": 1,
"onlinePlayers": []
}
? /player/:criteria
通过使用游戏内名称或 UUID 作为 :criteria 来检索特定玩家的详细信息。
示例响应:
{
"name": "PLAYER_NAME",
"online": true,
"uuid": "PLAYER_UUID",
"info": {
"currentChunkPos": {
"z": 1,
"x": 0
},
"currentPos": {
"z": 23.423937096484163,
"x": 7.907748838070694,
"y": 100.12983446114534
},
"dimension": "minecraft:the_nether"
}
}
? 面向开发者
本模组不仅适用于服务器所有者;它也是专为可扩展性而构建的!任何模组开发者都可以轻松注册自定义 API 路由,以暴露其模组的独特数据或功能。
1. 创建您的路由类
通过创建一个实现 APIRoute 接口的类来定义您的 API 端点。您可以使用 @RouteSettings 注解来配置其路径和行为。
import xyz.yoinky3000.server_info_api.annotations.RouteSettings;
import xyz.yoinky3000.server_info_api.api.APIRequest;
import xyz.yoinky3000.server_info_api.api.APIResponse;
import xyz.yoinky3000.server_info_api.api.APIRoute;
import net.minecraft.server.MinecraftServer; // 导入以获取服务器参数
// --- 选项 1:基本路由(不需要服务器)---
// 此路由将响应 "test",并且不需要 MinecraftServer 完全加载。
@RouteSettings(path = "/my-simple-test-route") // requireMinecraftServer 默认为 false
public class MySimpleTestRoute implements APIRoute {
@Override
public APIResponse handle(APIRequest apiRequest) {
// 在这里您无法访问 MinecraftServer 对象
return new APIResponse(APIResponse.HttpStatus.OK, APIResponse.MimeType.TEXT_PLAIN, "Hello from my simple route!");
}
}
// --- 选项 2:需要 MinecraftServer 的路由 ---
// 此路由仅在 MinecraftServer 就绪后才提供服务。
// 如果在服务器就绪之前收到请求,将自动发送 HTTP 500 (INTERNAL_SERVER_ERROR)。
@RouteSettings(path = "/my-server-data-route", requireMinecraftServer = true)
public class MyServerDataRoute implements APIRoute {
@Override
public APIResponse handle(APIRequest request, MinecraftServer server) {
// 如果 requireMinecraftServer 为 true,这里的 'server' 保证不为 null
int onlinePlayers = server.getCurrentPlayerCount();
return new APIResponse(APIResponse.HttpStatus.OK, APIResponse.MimeType.TEXT_PLAIN,
"Currently online players: " + onlinePlayers);
}
}
解释 @RouteSettings:
path: API 端点(例如 /my-custom-data)。
requireMinecraftServer: 如果为 true,则路由仅在全局初始化完成后的 Minecraft 服务器时才提供服务。如果在服务器就绪之前收到请求,将自动发送 HTTP 500 (Internal Server Error) 响应。默认为 false。
2. 注册您的路由类
创建好 APIRoute 类后,将其注册到 ServerInfoAPI。您可以在任何时候进行注册,即使是在 onInitialize 之外,如果您的模组逻辑需要的话。一旦注册,路由即刻生效!
import xyz.yoinky3000.server_info_api.ServerInfoAPI;
import net.fabricmc.api.ModInitializer; // 假设是 Fabric ModInitializer
public class CustomMod implements ModInitializer {
@Override
public void onInitialize() {
// ... 您的其他初始化代码 ...
// 使用注解注册路由(推荐以提高清晰度)
ServerInfoAPI.registerRoute(new MyServerDataRoute()); // 注解处理路径和服务器要求
// 或者,如果您更喜欢不使用注解,或者用于动态路径:
// 您可以显式定义路径、服务器要求和覆盖行为。
// ServerInfoAPI.registerRoute("/my-dynamic-route", new MySimpleTestRoute());
// ServerInfoAPI.registerRoute("/admin-data", new MyServerDataRoute(), true, true); // 路径, 路由, requiresServer, override
System.out.println("已注册自定义 API 路由!");
}
}
用于灵活性的 registerRoute 重载方法:
ServerInfoAPI 提供了多种 registerRoute 方法,供您完全掌控:
public static APIHandler.RegisterResult registerRoute(APIRoute route): 注册由其 @RouteSettings 注解配置的路由。默认情况下 override 为 false。
public static APIHandler.RegisterResult registerRoute(APIRoute route, boolean override): 注册带注解的路由,允许您显式覆盖同一路径下已存在的路由。
public static APIHandler.RegisterResult registerRoute(String path, APIRoute route): 使用指定的 path 注册路由。默认情况下 requireMinecraftServer 为 false 且 override 为 false。
public static APIHandler.RegisterResult registerRoute(String path, APIRoute route, boolean override): 使用指定的 path 注册路由,允许您覆盖已存在的路由。
public static APIHandler.RegisterResult registerRoute(String path, APIRoute route, boolean requireMinecraftServer, boolean override): 提供对 path、APIRoute 实例、requireMinecraftServer 状态以及 override 行为的完全控制。
3. 动态路由模式
您可以在路由路径中使用 :SOMETHING_HERE 定义动态段。这对于 /player/:criteria 之类的路由非常有用,其中 criteria 是玩家名称或 UUID 的占位符。
要在您的 handle 方法中访问这些动态参数:
import xyz.yoinky3000.server_info_api.api.APIRequest;
import xyz.yoinky3000.server_info_api.api.APIResponse;
import xyz.yoinky3000.server_info_api.api.APIRoute;
import net.minecraft.server.MinecraftServer;
@RouteSettings(path = "/my-data/:item_id")
public class ItemDataRoute implements APIRoute {
@Override
public APIResponse handle(APIRequest request, MinecraftServer server) {
// 从 URL 中获取 'item_id' 段的值
String itemId = request.routeParams().get("item_id"); //
if (itemId != null) {
// 获取此物品 ID 数据的逻辑
return new APIResponse(APIResponse.HttpStatus.OK, APIResponse.MimeType.TEXT_PLAIN, "请求的物品 ID: " + itemId);
} else {
return new APIResponse(APIResponse.HttpStatus.BAD_REQUEST, APIResponse.MimeType.TEXT_PLAIN, "未提供物品 ID。");
}
}
}
? 贡献与支持
欢迎在 GitHub 仓库上提交问题以报告错误或提出功能请求。始终欢迎贡献!
? Server Info API Mod
Access and Extend Server Information via HTTP API
This mod is designed to empower Minecraft server owners and mod developers by providing a robust and easily extendable HTTP API. Get real-time server statistics and seamlessly integrate your server's and mod's data into external applications or web interfaces.
✨ Why You Need This Mod
Are you looking to:
- ? Monitor your server via HTTP request?
- ? Display live player counts on your website?
- ? Create custom Discord bots that interact with your server data?
- ? Allow other mods to effortlessly expose their data through a unified API?
The Server Info API mod makes all of this a lot easier! It sets up a dedicated API endpoint for your Minecraft server, offering both essential predefined routes and a flexible system for developers to add their own.
⚙️ Quick Setup
By default, the API runs on port 8080. You can easily change this port to suit your needs by modifying the apiPort setting in config/Server Info API/settings.json.
? API Endpoints - What You Can Access
This mod comes with powerful predefined routes to get you started immediately.
? /status
Get a comprehensive overview of your server's vital statistics, including disk usage, CPU load, RAM consumption, and current player counts.
Example Response:
{
"disk": {
"totalGB": 1606,
"freeGB": 343,
"usedMB": 25
},
"players": {
"online": 0,
"max": 20
},
"cpu": {
"usagePercent": 9.865470852017937
},
"ram": {
"totalMB": 63033,
"usedMB": 31469
}
}
? /players
Show the total number of players who have ever joined your server and see a list of all currently online players.
Example Response:
{
"totalPlayers": 1,
"onlinePlayers": []
}
? /player/:criteria
Retrieve detailed information about a specific player by using their in-game name or UUID as the :criteria.
Example Response:
{
"name": "PLAYER_NAME",
"online": true,
"uuid": "PLAYER_UUID",
"info": {
"currentChunkPos": {
"z": 1,
"x": 0
},
"currentPos": {
"z": 23.423937096484163,
"x": 7.907748838070694,
"y": 100.12983446114534
},
"dimension": "minecraft:the_nether"
}
}
? For Developers
This mod isn't just for server owners; it's built with extensibility in mind! Any mod developer can easily register custom API routes to expose their mod's unique data or functionalities.
1. Create Your Route Class
Define your API endpoint by creating a class that implements the APIRoute interface. You can use the @RouteSettings annotation to configure its path and behavior.
import xyz.yoinky3000.server_info_api.annotations.RouteSettings;
import xyz.yoinky3000.server_info_api.api.APIRequest;
import xyz.yoinky3000.server_info_api.api.APIResponse;
import xyz.yoinky3000.server_info_api.api.APIRoute;
import net.minecraft.server.MinecraftServer; // Import for the server parameter
// --- Option 1: Basic Route (no server required) ---
// This route will respond with "test" and does not require the MinecraftServer to be fully loaded.
@RouteSettings(path = "/my-simple-test-route") // requireMinecraftServer is false by default
public class MySimpleTestRoute implements APIRoute {
@Override
public APIResponse handle(APIRequest apiRequest) {
// You don't have access to the MinecraftServer object here
return new APIResponse(APIResponse.HttpStatus.OK, APIResponse.MimeType.TEXT_PLAIN, "Hello from my simple route!");
}
}
// --- Option 2: Route Requiring MinecraftServer ---
// This route will only serve requests once the MinecraftServer is ready.
// If a request comes in before the server is ready, an HTTP 500 (INTERNAL_SERVER_ERROR)
// will be automatically sent.
@RouteSettings(path = "/my-server-data-route", requireMinecraftServer = true)
public class MyServerDataRoute implements APIRoute {
@Override
public APIResponse handle(APIRequest request, MinecraftServer server) {
// Here, 'server' is guaranteed not to be null if requireMinecraftServer is true
int onlinePlayers = server.getCurrentPlayerCount();
return new APIResponse(APIResponse.HttpStatus.OK, APIResponse.MimeType.TEXT_PLAIN,
"Currently online players: " + onlinePlayers);
}
}
@RouteSettings explained:
path: The API endpoint (e.g., /my-custom-data).
requireMinecraftServer: If true, the route will only serve requests when the Minecraft server is fully initialized. If a request arrives before the server is ready, an HTTP 500 (Internal Server Error) response is sent automatically. This is false by default.
2. Register Your Route Class
Once you've created your APIRoute class, register it with the ServerInfoAPI. You can do this at any time, even outside of onInitialize if your mod's logic requires it. The route becomes active as soon as it's registered!
import xyz.yoinky3000.server_info_api.ServerInfoAPI;
import net.fabricmc.api.ModInitializer; // Assuming Fabric ModInitializer
public class CustomMod implements ModInitializer {
@Override
public void onInitialize() {
// ... your other initialization code ...
// Registering a route using the annotation (recommended for clarity)
ServerInfoAPI.registerRoute(new MyServerDataRoute()); // The annotation handles path and server requirement
// Alternatively, if you prefer not to use annotations, or for dynamic paths:
// You can explicitly define path, server requirement, and override behavior.
// ServerInfoAPI.registerRoute("/my-dynamic-route", new MySimpleTestRoute());
// ServerInfoAPI.registerRoute("/admin-data", new MyServerDataRoute(), true, true); // Path, Route, requiresServer, override
System.out.println("Custom API routes registered!");
}
}
registerRoute Overloads for Flexibility:
The ServerInfoAPI offers various registerRoute methods to give you full control:
public static APIHandler.RegisterResult registerRoute(APIRoute route): Registers a route configured by its @RouteSettings annotation. override is false by default.
public static APIHandler.RegisterResult registerRoute(APIRoute route, boolean override): Registers an annotated route, allowing you to explicitly override existing routes at the same path.
public static APIHandler.RegisterResult registerRoute(String path, APIRoute route): Registers a route with a specified path. requireMinecraftServer is false and override is false by default.
public static APIHandler.RegisterResult registerRoute(String path, APIRoute route, boolean override): Registers a route with a specified path, allowing you to override existing routes.
public static APIHandler.RegisterResult registerRoute(String path, APIRoute route, boolean requireMinecraftServer, boolean override): Provides full control over path, APIRoute instance, requireMinecraftServer status, and override behavior.
3. Dynamic Route Patterns
You can define dynamic segments in your route paths using :SOMETHING_HERE. This is perfect for routes like /player/:criteria where criteria is a placeholder for a player name or UUID.
To access these dynamic parameters within your handle method:
import xyz.yoinky3000.server_info_api.api.APIRequest;
import xyz.yoinky3000.server_info_api.api.APIResponse;
import xyz.yoinky3000.server_info_api.api.APIRoute;
import net.minecraft.server.MinecraftServer;
@RouteSettings(path = "/my-data/:item_id")
public class ItemDataRoute implements APIRoute {
@Override
public APIResponse handle(APIRequest request, MinecraftServer server) {
// Retrieve the value of the 'item_id' segment from the URL
String itemId = request.routeParams().get("item_id"); //
if (itemId != null) {
// Logic to fetch data for this item ID
return new APIResponse(APIResponse.HttpStatus.OK, APIResponse.MimeType.TEXT_PLAIN, "Requested item ID: " + itemId);
} else {
return new APIResponse(APIResponse.HttpStatus.BAD_REQUEST, APIResponse.MimeType.TEXT_PLAIN, "Item ID not provided.");
}
}
}
? Contribution & Support
Feel free to open issues for bug reports or feature requests on the GitHub repository. Contributions are always welcome!
评论 0
登录后参与评分
还没有评论,来抢沙发吧