NDP Reforged SDK 使用文档

本文档详细描述 NDP Reforged API 的多语言 SDK使用方法，适用于 Minecraft 服务器反作弊集成场景。

1. SDK 概述

语言	依赖
Python	`requests`
Java	OkHttp 4.x + Gson 2.x
Go	无 (标准库)
C#	.NET 6+

Base URL: https://api.ndpreforged.com

2. 安装方式

Python

方式一：pip 安装

Bash
pip install ndpreforged

方式二：whl 包安装

下载 ndpreforged.whl，然后：

Bash
pip install ndpreforged-1.0.0-py3-none-any.whl

Java

下载 ndpreforged-sdk.jar ，然后：

Maven (pom.xml)

XML
<dependency>
    <groupId>com.ndpreforged</groupId>
    <artifactId>ndpreforged-sdk</artifactId>
    <version>1.0.0</version>
    <scope>system</scope>
    <systemPath>path/to/ndpreforged-sdk.jar</systemPath>
</dependency>

编译

Bash
cd sdk/java
javac -encoding UTF-8 -d target src/main/java/com/ndpreforged/NDPReforgedClient.java

Go

下载 ndpreforged.go ，然后：

Bash
go mod init your/module
go mod tidy
# 将 ndpreforged.go 放入项目目录
go build

C#

下载 NDPReforged.cs ，然后：

项目引用

Bash
dotnet add package NDPReforged

或直接将 NDPReforged.cs 添加至项目。

编译

Bash
dotnet build -c Release

下载链接汇总

语言	文件	大小
Python	ndpreforged.whl	3.88 KB
Java	ndpreforged-sdk.jar	10.58 KB
Go	ndpreforged.go	7.98 KB
C#	NDPReforged.cs	7.74 KB

3. 初始化配置

Python

Python
from ndpreforged import NDPReforged

# 默认 Base URL + 30s 超时
client = NDPReforged()

# 自定义配置
client = NDPReforged(
    base_url="https://api.ndpreforged.com",
    timeout=60
)

Java

Java
import com.ndpreforged.NDPReforgedClient;

// 默认 30s 超时
NDPReforgedClient client = new NDPReforgedClient("https://api.ndpreforged.com");

// 自定义超时 (秒)
NDPReforgedClient client = new NDPReforgedClient("https://api.ndpreforged.com", 60);

Go

go
import "ndpreforged"

// 默认 30s 超时
client := ndpreforged.NewClient("https://api.ndpreforged.com")

// 自定义超时
client := ndpreforged.NewClientWithTimeout("https://api.ndpreforged.com", 60)

C#

csharp
using NDPReforged;

// 默认 30s 超时
var client = new NDPReforgedClient();

// 自定义配置
var client = new NDPReforgedClient("https://api.ndpreforged.com", 60);

4. API 列表

4.1 健康检查

验证 API 服务可用性。

SDK	方法签名
Python	`health_check() -> Dict`
Java	`healthCheck() -> ApiResponse`
Go	`HealthCheck() -> (*APIResponse, error)`
C#	`HealthCheckAsync() -> Task<ApiResponse>`

返回字段:

status: 服务状态 (running)

message: 响应消息

4.2 UUID 生成

生成唯一标识符，用于客户端注册。

SDK	方法签名
Python	`generate_uuid() -> Dict`
Java	`generateUuid() -> UuidResponse`
Go	`GenerateUUID() -> (*UUIDResponse, error)`
C#	`GenerateUuidAsync() -> Task<UuidResponse>`

返回字段:

uuid: 格式化的 UUID 字符串 (例: xxxx-xxxx-xxxx-xxxx)

4.3 Token 认证

验证 Token 的有效性。

SDK	方法签名
Python	`token_auth(token: str) -> Dict`
Java	`tokenAuth(String token) -> ApiResponse`
Go	`TokenAuth(token string) -> (*APIResponse, error)`
C#	`TokenAuthAsync(string token) -> Task<ApiResponse>`

4.4 权限检查

验证 Token 的上传权限。

SDK	方法签名
Python	`check_permission(token: str) -> Dict`
Java	`checkPermission(String token) -> ApiResponse`
Go	`CheckPermission(token string) -> (*APIResponse, error)`
C#	`CheckPermissionAsync(string token) -> Task<ApiResponse>`

4.5 添加封禁记录

将玩家/IP 添加至封禁列表。

SDK	方法签名
Python	`add_ban(token, player_id=None, ip=None, ipv6=None, online=False, mcuuid=None)`
Java	`addBan(BanRequest request) -> ApiResponse`
Go	`AddBan(BanRequest) -> (APIResponse, error)`
C#	`AddBanAsync(BanRequest request)` / `AddBanAsync(token, playerId, ...)`

BanRequest 字段:

字段	类型	必填	说明
`token`	String	是	授权令牌
`player_id`	String	否	玩家ID
`ip`	String	否	IPv4 地址
`ipv6`	String	否	IPv6 地址
`mcuuid`	String	否	Minecraft UUID
`online`	Boolean	是	是否在线 (影响路由)

至少需提供 player_id、ip、ipv6 或 mcuuid 其一。

4.6 删除封禁记录

从封禁列表移除指定记录。

SDK	方法签名
Python	`delete_ban(token, player_id=None, ip=None, ipv6=None, online=False, mcuuid=None)`
Java	`deleteBan(BanRequest request) -> ApiResponse`
Go	`DeleteBan(BanRequest) -> (APIResponse, error)`
C#	`DeleteBanAsync(BanRequest request)`

参数同 add_ban。

4.7 绑定信息

为封禁记录绑定额外标识。

SDK	方法签名
Python	`bind_info(token, ref_player_id=None, ref_ip=None, ref_ipv6=None, add_player_id=None, add_ip=None, add_ipv6=None, online=False, mcuuid=None)`
Java	`bindInfo(BindRequest request) -> ApiResponse`
Go	`BindInfo(BindRequest) -> (APIResponse, error)`
C#	`BindInfoAsync(BindRequest request)`

BindRequest 字段:

字段	类型	必填	说明
`token`	String	是	授权令牌
`ref_*`	String	否	参照信息 (源标识)
`add_*`	String	否	待绑定信息 (新增标识)
`online`	Boolean	是	是否在线

4.8 解绑信息

解除封禁记录的绑定标识。

SDK	方法签名
Python	`unbind_info(token, ref_player_id=None, ref_ip=None, ref_ipv6=None, add_player_id=None, add_ip=None, add_ipv6=None, online=False, mcuuid=None)`
Java	`unbindInfo(BindRequest request) -> ApiResponse`
Go	`UnbindInfo(BindRequest) -> (APIResponse, error)`
C#	`UnbindInfoAsync(BindRequest request)`

4.9 下载封禁列表

获取封禁列表文件下载 URL。

SDK	方法签名
Python	`download_banlist(token: str) -> Dict`
Java	`downloadBanlist(String token) -> DownloadResponse`
Go	`DownloadBanlist(token string) -> (*DownloadResponse, error)`
C#	`DownloadBanlistAsync(string token) -> Task<DownloadResponse>`

返回字段:

url: 封禁列表下载链接

4.10 下载完成通知

通知服务器客户端已完成封禁列表同步。

SDK	方法签名
Python	`download_complete(token: str) -> Dict`
Java	`downloadComplete(String token) -> ApiResponse`
Go	`DownloadComplete(token string) -> (*APIResponse, error)`
C#	`DownloadCompleteAsync(string token) -> Task<ApiResponse>`

4.11 上报拦截事件

上报作弊拦截统计数据。

SDK	方法签名
Python	`report_intercept(token: str) -> Dict`
Java	`reportIntercept(String token) -> StatsResponse`
Go	`ReportIntercept(token string) -> (*StatsResponse, error)`
C#	`ReportInterceptAsync(string token) -> Task<StatsResponse>`

返回字段:

total: 累计拦截次数

message: 响应消息

4.12 获取统计信息

获取全局拦截统计数据。

SDK	方法签名
Python	`get_stats() -> Dict`
Java	`getStats() -> StatsResponse`
Go	`GetStats() -> (*StatsResponse, error)`
C#	`GetStatsAsync() -> Task<StatsResponse>`

返回字段:

total: 全局累计拦截次数

5. 使用示例

5.1 健康检查与基础连接验证

Python

Python
client = NDPReforged()
try:
    result = client.health_check()
    if result.get('status') == 'running':
        print("API 服务正常")
except NDPError as e:
    print(f"连接失败: {e}")

Java

Java
NDPReforgedClient client = new NDPReforgedClient();
try {
    ApiResponse resp = client.healthCheck();
    if ("running".equals(resp.status)) {
        System.out.println("API 服务正常");
    }
} catch (NdpException e) {
    System.err.println("连接失败: " + e.getMessage());
}

Go

go
client := ndpreforged.NewClient("")
resp, err := client.HealthCheck()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Status: %s\n", resp.Status)

C#

csharp
var client = new NDPReforgedClient();
var resp = await client.HealthCheckAsync();
Console.WriteLine($"Status: {resp.Message}");

5.2 客户端注册流程

Python
client = NDPReforged()

# 1. 生成 UUID
uuid_resp = client.generate_uuid()
client_uuid = uuid_resp['uuid']

# 2. 注册客户端 (需服务端配合)
# register_client(client_uuid, metadata)

print(f"客户端 UUID: {client_uuid}")

5.3 封禁操作

Python

Python
client = NDPReforged()

# 添加封禁
client.add_ban(
    token="YOUR_TOKEN",
    player_id="griefer123",
    online=True
)

# 批量封禁 IP
client.add_ban(
    token="YOUR_TOKEN",
    ip="192.168.1.100",
    online=False
)

# 移除封禁
client.delete_ban(
    token="YOUR_TOKEN",
    player_id="griefer123",
    online=True
)

Java

Java
NDPReforgedClient client = new NDPReforgedClient("https://api.ndpreforged.com");

BanRequest req = new BanRequest("YOUR_TOKEN");
req.playerId = "griefer123";
req.online = true;

try {
    ApiResponse resp = client.addBan(req);
    System.out.println("封禁成功: " + resp.message);
} catch (NdpException e) {
    System.err.println("错误: " + e.getCode() + " - " + e.getMessage());
}

Go

go
client := ndpreforged.NewClient("")
req := &ndpreforged.BanRequest{
    Token:    "YOUR_TOKEN",
    Online:   true,
}
req.PlayerID = ndpreforged.StringPtr("griefer123")

resp, err := client.AddBan(req)
if err != nil {
    log.Fatal(err)
}
fmt.Println("封禁成功:", resp.Message)

C#

csharp
var client = new NDPReforgedClient();
var resp = await client.AddBanAsync(new BanRequest
{
    Token = "YOUR_TOKEN",
    PlayerId = "griefer123",
    Online = true
});
Console.WriteLine($"Result: {resp.Message}");

5.4 封禁列表同步

Python
client = NDPReforged()

# 获取下载链接
dl_resp = client.download_banlist("YOUR_TOKEN")
download_url = dl_resp['url']

# 下载文件后通知完成
# client.download_complete("YOUR_TOKEN")

5.5 权限验证

Python
client = NDPReforged()

# 验证令牌有效性
auth_resp = client.token_auth("YOUR_TOKEN")
print(f"认证结果: {auth_resp}")

# 检查上传权限
perm_resp = client.check_permission("YOUR_TOKEN")
print(f"权限检查: {perm_resp}")

5.6 拦截数据上报

Python
client = NDPReforged()

# 上报拦截事件
stats = client.report_intercept("YOUR_TOKEN")
print(f"累计拦截: {stats['total']}")

# 查询全局统计
global_stats = client.get_stats()
print(f"全局拦截: {global_stats['total']}")

6. 错误处理

6.1 异常类型

SDK	异常类型	错误码字段
Python	`NDPError`	`.code`, `.message`
Java	`NdpException`	`.getCode()`
Go	`*APIError`	`.Code`, `.Message`
C#	`NdpException`	`.Code`

6.2 HTTP 状态码含义

状态码	含义	处理建议
200	成功	解析响应数据
400	请求参数错误	检查 token 格式及必填字段
401	认证失败	验证 token 有效性
403	权限不足	确认令牌权限等级
429	请求频率超限	实现退避重试机制
500	服务器内部错误	记录日志并重试

6.3 重试策略建议

Python
import time

def retry_request(func, max_retries=3, delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except NDPError as e:
            if e.code == 429:  # Rate limit
                time.sleep(delay * (attempt + 1))
            else:
                raise
    raise Exception("Max retries exceeded")

附录：API 端点速查

功能	端点	方法
健康检查	`/`	GET
令牌认证	`/token/auth`	POST
权限检查	`/token/permission/auth`	POST
UUID生成	`/uuid/getuuid`	POST
添加封禁	`/bans/add`	POST
删除封禁	`/bans/del`	POST
绑定信息	`/bans/bind`	POST
解绑信息	`/bans/cbind`	POST
下载封禁列表	`/bans/download`	GET
下载完成	`/bans/download/done`	POST
上报拦截	`/stats/a`	POST
获取统计	`/stats/s`	GET

文档版本: 1.1 | 更新日期: 2026-05-29

*部分文档由AI制作(已经人工审查)

NDP Reforged SDK 使用文档

1. SDK 概述

2. 安装方式

Python

Java

Go

C#

下载链接汇总

3. 初始化配置

Python

Java

Go

C#

4. API 列表

4.1 健康检查

4.2 UUID 生成

4.3 Token 认证

4.4 权限检查

4.5 添加封禁记录

4.6 删除封禁记录

4.7 绑定信息

4.8 解绑信息

4.9 下载封禁列表

4.10 下载完成通知

4.11 上报拦截事件

4.12 获取统计信息

5. 使用示例

5.1 健康检查与基础连接验证

5.2 客户端注册流程

5.3 封禁操作

5.4 封禁列表同步

5.5 权限验证

5.6 拦截数据上报

6. 错误处理

6.1 异常类型

6.2 HTTP 状态码含义

6.3 重试策略建议

附录：API 端点速查

导航