NameMCAPI (EarthPol)
NameMCAPI 是一个轻量级的 Paper/Folia 兼容插件,它将 NameMC 的多个未记录的公共 API 端点暴露为共享的 Bukkit 服务。
它旨在供 EarthPol 生态系统(或其他地方)中的其他插件使用,无需抓取 HTML 或阻塞主服务器线程。
所有请求均为异步且可选缓存。
功能特性
- 异步、非阻塞 HTTP 请求
- Bukkit Services API 集成
- 基于 TTL 的响应缓存选项
- “获取最新数据”调用的缓存绕过
- 兼容 Paper 和 Folia
- API 与实现之间的清晰分离
支持的 NameMC 端点
当前支持以下 NameMC 端点:
GET /profile/{uuid}/friends
GET /profile/{uuid}/friends?with={uuid}
GET /server/{domain}/likes
GET /server/{domain}/likes?profile={uuid}
安装
- 将
NameMCAPI.jar 放入 /plugins 目录
- 重启服务器
- API 服务将自动注册
无需任何命令或权限。
配置
namemc:
base-url: "https://api.namemc.com"
http-timeout-ms: 6000
cache-ttl-ms: 60000
配置选项
-
base-url
- 默认为
https://api.namemc.com
-
http-timeout-ms
-
cache-ttl-ms
- 缓存响应的存活时间(TTL)
- 设置为
0 以完全禁用缓存
在其他插件中使用 NameMCAPI
NameMCAPI 暴露了一个名为 NameMCAPIService 的 Bukkit 服务。
- 获取服务
import com.earthpol.namemc.api.NameMCAPIService;
import org.bukkit.Bukkit;
NameMCAPIService nameMC =
Bukkit.getServicesManager().load(NameMCAPIService.class);
if (nameMC == null) {
getLogger().severe("NameMCAPI not found! Is the plugin installed?");
return;
}
这通常应在 onEnable 中完成一次。
- 获取玩家的好友列表
UUID uuid = UUID.fromString("d550441b-5fcf-448c-a756-5fa391b89a46");
// false = 获取最新数据,true = 使用缓存
nameMC.getFriends(uuid, false).thenAccept(friends -> {
getLogger().info("Friend count: " + friends.size());
});
- 检查两个资料是否为好友
UUID a = UUID.fromString("403e6cb7-a6ca-440a-8041-7fb1e579b5a5");
UUID b = UUID.fromString("ac62cc72-ce09-4fd4-9018-38b92ef4d619");
nameMC.areFriends(a, b, true).thenAccept(areFriends -> {
if (areFriends) {
getLogger().info("They are friends on NameMC");
}
});
- 获取服务器点赞数
nameMC.getServerLikes("play.earthpol.com", true)
.thenAccept(likes ->
getLogger().info("Server likes: " + likes)
);
- 检查玩家是否点赞了服务器
UUID profile = UUID.fromString("3bd5b91a-7532-4acf-bd2a-2a739206865b");
nameMC.hasProfileLikedServer("play.earthpol.com", profile, false)
.thenAccept(liked -> {
if (liked) {
getLogger().info("Player has liked the server");
}
});
线程注意事项(重要)
所有回调均在主线程之外运行。
如果你需要与 Bukkit 对象(玩家、世界、计分板等)交互,必须切换回主线程:
nameMC.getFriends(uuid, true).thenAccept(friends -> {
Bukkit.getScheduler().runTask(this, () -> {
player.sendMessage("You have " + friends.size() + " NameMC friends");
});
});
Maven 依赖(BitworksMC Nexus)
NameMCAPI 已发布到 BitworksMC Nexus 仓库,可以直接通过 Maven 使用。
- 添加仓库
<repositories>
<repository>
<id>bitworksmc-releases</id>
<url>https://nexus.bitworksmc.com/repository/maven-releases/</url>
</repository>
</repositories>
- 添加依赖
<dependency>
<groupId>com.earthpol</groupId>
<artifactId>NameMCAPI</artifactId>
<version>2.0.0</version>
<scope>provided</scope>
</dependency>
设计说明
- NameMCAPI 不抓取 HTML
- 使用 NameMC 可公开访问的 JSON 端点
- 响应和端点属于未记录内容,可能会发生变化
- 失败情况不会缓存
- 缓存会对进行中的请求去重,以避免风暴效应
许可证与免责声明
本项目不与 NameMC 或 Mojang/Microsoft 有关联。
NameMC 端点属于未记录内容,随时可能更改或消失。
请自行承担使用风险。
NameMCAPI (EarthPol)
NameMCAPI is a lightweight Paper/Folia-safe plugin that exposes several of NameMC’s undocumented public API endpoints as a shared Bukkit service.
It is designed to be used by other plugins in the EarthPol ecosystem (or elsewhere) without scraping HTML or blocking the main server thread.
All requests are asynchronous and optionally cached.
Features
- Async, non-blocking HTTP requests
- Bukkit Services API integration
- Optional TTL-based response caching
- Cache bypass for “fetch latest” calls
- Paper & Folia compatible
- Clean separation between API and implementation
Supported NameMC Endpoints
The following NameMC endpoints are currently supported:
GET /profile/{uuid}/friends
GET /profile/{uuid}/friends?with={uuid}
GET /server/{domain}/likes
GET /server/{domain}/likes?profile={uuid}
Installation
- Place
NameMCAPI.jar into your /plugins directory
- Restart the server
- The API service will register automatically
No commands or permissions are required.
Configuration
namemc:
base-url: "https://api.namemc.com"
http-timeout-ms: 6000
cache-ttl-ms: 60000
Configuration Options
-
base-url
- Defaults to
https://api.namemc.com
-
http-timeout-ms
- HTTP request timeout in milliseconds
-
cache-ttl-ms
- Time-to-live for cached responses
- Set to
0 to disable caching entirely
Using NameMCAPI in Other Plugins
NameMCAPI exposes a Bukkit service called NameMCAPIService.
- Obtaining the Service
import com.earthpol.namemc.api.NameMCAPIService;
import org.bukkit.Bukkit;
NameMCAPIService nameMC =
Bukkit.getServicesManager().load(NameMCAPIService.class);
if (nameMC == null) {
getLogger().severe("NameMCAPI not found! Is the plugin installed?");
return;
}
This should typically be done once in onEnable.
- Fetching a Player’s Friends List
UUID uuid = UUID.fromString("d550441b-5fcf-448c-a756-5fa391b89a46");
// false = fetch latest, true = use cache
nameMC.getFriends(uuid, false).thenAccept(friends -> {
getLogger().info("Friend count: " + friends.size());
});
- Checking if Two Profiles Are Friends
UUID a = UUID.fromString("403e6cb7-a6ca-440a-8041-7fb1e579b5a5");
UUID b = UUID.fromString("ac62cc72-ce09-4fd4-9018-38b92ef4d619");
nameMC.areFriends(a, b, true).thenAccept(areFriends -> {
if (areFriends) {
getLogger().info("They are friends on NameMC");
}
});
- Getting Server Like Count
nameMC.getServerLikes("play.earthpol.com", true)
.thenAccept(likes ->
getLogger().info("Server likes: " + likes)
);
- Checking if a Player Liked a Server
UUID profile = UUID.fromString("3bd5b91a-7532-4acf-bd2a-2a739206865b");
nameMC.hasProfileLikedServer("play.earthpol.com", profile, false)
.thenAccept(liked -> {
if (liked) {
getLogger().info("Player has liked the server");
}
});
Threading Notes (IMPORTANT)
All callbacks run off the main thread.
If you need to interact with Bukkit objects (players, worlds, scoreboards, etc.), you must switch back to the main thread:
nameMC.getFriends(uuid, true).thenAccept(friends -> {
Bukkit.getScheduler().runTask(this, () -> {
player.sendMessage("You have " + friends.size() + " NameMC friends");
});
});
Maven Dependency (BitworksMC Nexus)
NameMCAPI is published to the BitworksMC Nexus repository and can be consumed directly via Maven.
- Add the repository
<repositories>
<repository>
<id>bitworksmc-releases</id>
<url>https://nexus.bitworksmc.com/repository/maven-releases/</url>
</repository>
</repositories>
- Add the dependency
<dependency>
<groupId>com.earthpol</groupId>
<artifactId>NameMCAPI</artifactId>
<version>2.0.0</version>
<scope>provided</scope>
</dependency>
Design Notes
- NameMCAPI does not scrape HTML
- Uses NameMC’s publicly accessible JSON endpoints
- Responses and endpoints are undocumented and may change
- Failures are not cached
- Cache deduplicates in-flight requests to avoid stampedes
License / Disclaimer
This project is not affiliated with NameMC or Mojang/Microsoft.
NameMC endpoints are undocumented and may change or disappear at any time.
Use at your own risk.
评论 0
登录后参与评分
还没有评论,来抢沙发吧