Fabric Request

🌏 中文

这是什么？

Fabric Request 是一个 库模组（library mod），本身没有玩法功能。它为其他模组提供一套统一、异步、安全的对外 HTTP/HTTPS 请求 API。

• ✅ 服务端 + 客户端都需安装，两端 API 完全一致
• ✅ 异步优先：默认返回 CompletableFuture，绝不卡游戏主线程
• ✅ 托管线程池：守护线程 + 随退出优雅关闭
• ✅ 安全可控：白/黑名单、私网拦截、超时、UA，全部走配置
• ✅ JSON 友好：复用游戏自带 Gson，response.json(Type.class)
• ✅ 零第三方依赖：仅用 JDK 内置 java.net.http.HttpClient

快速上手（其他模组接入）

1. 把 Fabric Request 的 jar 放进 mods/（服务端 + 客户端都放）。
2. 在你模组的 fabric.mod.json 的 depends 加："fabricrequest": "*"。
3. 直接调用：

import com.kscm.fabricrequest.FabricRequest;

FabricRequest.get("https://api.example.com/status")
    .header("Accept", "application/json")
    .execute()                                   // -> CompletableFuture<FabricResponse>
    .thenAccept(res -> System.out.println(res.statusCode() + " " + res.body()))
    .exceptionally(err -> { err.printStackTrace(); return null; });

⚠️ 回调运行在工作线程。要改游戏状态/发聊天，请切回主线程（server.execute(...) 或客户端 client.execute(...)）。

版本矩阵

自行构建

cd versions/1.20.1      # 或 1.21.1 / 26.1
./gradlew build         # Windows: gradlew.bat build
# 产物 / output: build/libs/fabricrequest-1.0.0.jar

构建示例模组（需先构建对应库）：

cd examples/example-mod
./gradlew build         # 进游戏输入 /frdemo 触发一次真实 GET

构建状态 Build status

• 1.20.1 ✅ 与 1.21.1 ✅ 的 fabricrequest-1.0.0.jar（含 sources jar）已在本环境构建验证。
• examples/example-mod ✅ 的 fabricrequest-demo-1.0.0.jar 已构建验证。
• 26.1 ⚠️ 源码完整，但需 JDK 25 + Gradle 9.5+（Loom 1.17.18 要求）。当前沙箱仅有 Gradle 8.8 与 JDK 21/25，Gradle 9.5 未发布/不可下载，故 26.1 的 jar 未在此产出；在你本机具备该工具链后执行 gradle build 即可。

目录结构

versions/{1.20.1,1.21.1,26.1}/  # 三版本独立工程（文件夹分区）
examples/example-mod/           # 可运行示例
docs/API.md, docs/USAGE.md      # 中英双语文档
index.html                      # 商业风格公开页（浅/深色）

📖 详细文档：docs/API.md · docs/USAGE.md

🌐 English

What is this?

Fabric Request is a library mod with no gameplay of its own. It gives other mods a unified, asynchronous, safe API for outbound HTTP/HTTPS requests.

• ✅ Install on both server and client — identical API on both sides
• ✅ Async-first — returns CompletableFuture, never blocks the game thread
• ✅ Managed thread pool — daemon threads, graceful shutdown
• ✅ Safe — allow/block lists, private-network guard, timeouts, UA — all config-driven
• ✅ JSON-friendly — reuses the game's bundled Gson: response.json(Type.class)
• ✅ Zero third-party deps — only the JDK's built-in java.net.http.HttpClient

Quick start (for consumer mods)

1. Drop the Fabric Request jar into mods/ (both server and client).
2. Add "fabricrequest": "*" to your mod's fabric.mod.json depends.
3. Call it:

import com.kscm.fabricrequest.FabricRequest;

FabricRequest.post("https://api.example.com/submit")
    .bodyJson(myPojo)
    .timeout(java.time.Duration.ofSeconds(10))
    .execute()
    .thenAccept(res -> {
        if (res.isSuccessful()) {
            MyData data = res.json(MyData.class);
        }
    });

⚠️ Callbacks run on a worker thread. Hop back to the main thread before touching game state.

Version matrix

Build it yourself

cd versions/1.20.1      # or 1.21.1 / 26.1
./gradlew build         # Windows: gradlew.bat build
# output: build/libs/fabricrequest-1.0.0.jar

Build status

• 1.20.1 ✅ and 1.21.1 ✅ fabricrequest-1.0.0.jar (with sources jar) are built and verified here.
• examples/example-mod ✅ fabricrequest-demo-1.0.0.jar is built and verified.
• 26.1 ⚠️ source is complete, but it needs JDK 25 + Gradle 9.5+ (required by Loom 1.17.18). This sandbox only has Gradle 8.8 and JDK 21/25, and Gradle 9.5 is not published/available, so the 26.1 jar is not produced here. Run gradle build on a machine with that toolchain.

📖 Full docs: docs/API.md · docs/USAGE.md