野兽先辈的HTTP路由器

野兽先辈的HTTP路由器

HomoHttpRouter 是一个共享 HTTP 服务和动态路由中心,专为 Minecraft 模组开发者(实际上是我自己)设计,允许多个模组复用同一个 HTTP 端口,并通过事件系统动态注册它们的 API。

工具

HomoHttpRouter

本模块 70% 的代码由 GTP-5.1 编写,其余 30% 由“人工智障”Heer!(我)编写。

icon.png

适用于 Minecraft 模组的共享 HTTP 路由框架

HomoHttpRouter 是一个为 Minecraft Forge 模组开发者设计的轻量级 HTTP 服务聚合框架。 它允许多个模组共享同一个 HTTP 端口,并通过事件系统动态注册路由,从而避免每个模组都需要单独启动独立的 HTTP 服务。

它本质上是 Minecraft 服务器内置的:

  • 路由中心
  • 自动文档生成器

基于成熟的 Netty 和 FastJSON2,设计轻量、稳定且易于扩展。


✨ 特性

🔌 共享 HTTP 端口

所有模组挂载在同一个 HTTP 服务上,避免端口冲突和重复的网络资源占用。

⚙️ 事件驱动的路由注册

模组在启动时监听 HttpServiceBuildEvent,并自动注册路由前缀和处理器。无需自行创建服务器。

📦 Netty 请求/响应标准

你的路由处理器将接收到:

  • RestRequest
  • 你需要返回 RestResponse

📝 自动生成文档

HomoHttpRouter 内置两个文档端点:

  • /docs → 自动生成的 HTML API 文档
  • /docs.json → 由 FastJSON2 输出的 JSON 文档(可用于外部生成器 / UI)

文档会根据你注册的 RouteInfo 自动生成。

🔧 可配置端口

端口号可在 Forge 配置中调整:

[http]
    # 要监听的端口
    port = 11451

📦 安装

在服务端将 HomoHttpRouter 作为依赖模组安装,其他模组即可自动注册路由。

从源代码构建:

git clone https://github.com/yourname/HomoHttpRouter.git
./gradlew build

构建完成后,你可以在 build/libs/ 中找到 jar 文件。


🔧 配置

主配置文件:

config/homohttprouter-server.toml

内容:

[http]
    # 要监听的端口
    port = 11451

修改配置后,重启服务器使更改生效。


🧩 用法(模组开发者指南)

其他模组可以通过监听 HttpServiceBuildEvent 来注册其 HTTP 路由。

第 1 步:监听事件

@EventBusSubscriber
public class AwhRoutes {
    @SubscribeEvent
    private static void onHttp(HttpServiceBuildEvent e){
        RouterRegistry registry = e.getRegistry();

        // 创建 RouteInfo
        RouteInfo info = new RouteInfo.Builder("mymod", "/mymod")
                .description("MyMod HTTP API")
                .route("GET", "/status", "Check service status", "", "OK")
                .build();

        // 注册 RouteInfo
        registry.register(info, restRequest -> RestResponse.ok());
    }
}

第 2 步:从请求中获取参数

@EventBusSubscriber
public class AwhRoutes {
    @SubscribeEvent
    private static void onHttp(HttpServiceBuildEvent e){
        RouterRegistry registry = e.getRegistry();

        // 创建 RouteInfo
        RouteInfo info = new RouteInfo.Builder("mymod", "/mymod")
                .description("MyMod HTTP API")
                .route("GET", "/status", "Check service status", "", "OK")
                .build();

        // 注册 RouteInfo
        registry.register(info, restRequest -> {
            // 像这样从请求中获取参数:/status?id=1
            if(restRequest.matchTemplate("/status")){
                // 你应该在模板中忽略 ?id=1
                String id = restRequest.queryParam("id");
                return RestResponse.ok(id);
            }
            
            // 或者像这样获取路径参数:/status/1
            if(restRequest.matchTemplate("/status/<id>")){
                String id = restRequest.pathParam("id");
                return RestResponse.ok(id);
            }

});
    }
}

📃 自动文档

只需访问:

http://your server address:[port]/docs

然后你就能看到自动渲染的 HTML 文档:

访问:

http://localhost:11451/docs.json

将返回:

{
  "routes": [
    {
      "modId": "yourmodid",
      "prefix": "/mymod",
      "description": "MyMod HTTP API",
      "endpoints": [
        {
          "method": "GET",
          "path": "/status",
          "summary": "Check server status",
          "bodySchema": "",
          "returns": "{ok:true}"
        }
      ]
    }
  ]
}

🛠️ 开发环境

包含的依赖:

com.squareup.okhttp3:okhttp:4.12.0
com.alibaba.fastjson2:fastjson2:2.x.x

Gradle 示例:

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.alibaba.fastjson2:fastjson2:2.0.48"
}

🤝 贡献

欢迎提交 PR 或 issue 来扩展功能,例如:

  • 中间件
  • 认证(token / API key)
  • WebSocket 支持
  • OpenAPI 3.0 导出
  • 文件上传(multipart)

📄 许可证

MIT License