R3944Realms/MCLTDWhitelistSystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
65584bb8d8
MCLTDWhitelistSystem/docs/whitelist-api-zh.md

7.4 KiB
Raw Blame History

白名单 API 接口文档

基础地址

https://your_host_url/api/whitelist

鉴权

所有接口均需鉴权，任选以下一种方式：

方式 示例
X-API-Key 请求头 -H "X-API-Key: <token>"
X-API-TOKEN 请求头 -H "X-API-TOKEN: <token>"
Query 参数 ?apiKey=<token>
管理员 Session Cookie 浏览器登录 /admin/login 后自动携带

鉴权失败响应（HTTP 403）：

{"code": 403, "msg": "无权限：API Key 无效或未提供", "data": null}

通用响应格式

所有接口统一返回以下结构：

{
  "code": 200,
  "msg": "提示信息",
  "count": 0,
  "data": {}
}
HTTP 状态码 code 含义
200 200 操作成功
200 500 业务错误（如玩家不存在、RCON 连接失败）
403 403 鉴权失败

接口列表

1. 获取白名单列表

GET /api/whitelist/list

查询玩家记录（默认 status=1 已通过）。

请求参数：

参数名 类型 必填 默认值 说明
playerName String 否 — 按玩家名筛选
page Integer 否 1 页码
size Integer 否 10 每页条数
all Boolean 否 false true 时忽略分页，一次性返回全部数据

分页查询：

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/list?page=1&size=10&playerName=Steve"

全部查询（不分页）：

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/list?all=true"
返回示例 
{
  "code": 200,
  "msg": "查询成功",
  "count": 42,
  "data": [
    {
      "id": 1,
      "playerName": "Steve",
      "uuid": "8667ba71b85a4004af54457a9734eed7",
      "qq": "123456789",
      "status": 1,
      "description": "我是建筑党",
      "createTime": "2026-06-01T12:00:00",
      "regionCode": 110000,
      "regionFullName": "北京市",
      "operatorId": 1,
      "operatorUsername": "admin",
      "operatorNickname": "管理员",
      "totalScore": 85,
      "emailActive": true
    }
  ]
}

2. 获取待审核列表

GET /api/whitelist/pending

分页查询待审核的玩家（status=2）。

请求参数： 同 /list（含 all 参数）。

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/pending?page=1&size=10"

3. 获取已拒绝列表

GET /api/whitelist/rejected

分页查询已被拒绝的玩家（status=0）。

请求参数： 同 /list（含 all 参数）。

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/rejected?page=1&size=10"

4. 通过审核（加入白名单）

POST /api/whitelist/approve/{id}

通过申请，通过 RCON 将玩家加入 Minecraft 服务器白名单。 使用 API Key 鉴权时，操作员记录为 null。

路径参数：

参数名 类型 说明
id Integer 玩家 ID

成功响应：

{"code": 200, "msg": "已加入白名单", "data": null}

失败响应：

{"code": 500, "msg": "操作失败，Rcon连接错误或玩家不存在", "data": null}

curl -X POST -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/approve/1"

5. 拒绝申请

POST /api/whitelist/reject/{id}

拒绝申请，设置状态为 0 并发送邮件通知。

路径参数： 同 approve。

curl -X POST -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/reject/1"

成功响应：

{"code": 200, "msg": "已拒绝申请", "data": null}

6. 从白名单移除

DELETE /api/whitelist/remove/{id}

通过 RCON 从 Minecraft 白名单移除并删除记录，同时发送邮件通知。

curl -X DELETE -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/remove/1"

成功响应：

{"code": 200, "msg": "已从白名单移除", "data": null}

7. 批量通过

POST /api/whitelist/batchApprove

请求体：

[1, 2, 3, 5]

curl -X POST -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[1,2,3]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchApprove"

成功响应：

{"code": 200, "msg": "成功处理：3/3", "data": null}

部分成功响应：

{"code": 200, "msg": "成功处理：2/3", "data": null}

8. 批量拒绝

POST /api/whitelist/batchReject

请求体： [1, 2, 3]

curl -X POST -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[4,5]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchReject"

9. 批量移除

DELETE /api/whitelist/batchRemove

请求体： [1, 2, 3]

curl -X DELETE -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[1,2]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchRemove"

成功响应：

{"code": 200, "msg": "成功移除：2/2", "data": null}

10. 白名单统计

GET /api/whitelist/stats

返回各状态的申请数量。

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/stats"

响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "approved": 42,
    "pending": 5,
    "rejected": 10
  }
}

11. 查询玩家白名单状态

GET /api/whitelist/check/{playerName}

按 Minecraft 用户名查询申请状态。

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/check/Steve"

响应（存在）：

{
  "code": 200,
  "data": {
    "exists": true,
    "status": 1,
    "playerName": "Steve",
    "qq": "12345",
    "uuid": "8667ba71b85a4004af54457a9734eed7",
    "statusText": "已通过"
  }
}

响应（不存在）：

{
  "code": 200,
  "data": {
    "exists": false
  }
}

statusText 对照表：

status statusText
0 已拒绝
1 已通过
2 待审核

12. 获取玩家得分

GET /api/whitelist/score/{id}

查询玩家的答题总分。

curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/score/1"

响应示例：

{
  "code": 200,
  "data": {
    "playerId": 1,
    "totalScore": 85
  }
}

失败响应：

{"code": 500, "msg": "玩家不存在", "data": null}

PlayerInfo 字段说明

字段 类型 说明
id Integer 玩家 ID
playerName String Minecraft 用户名
uuid String Mojang 正版 UUID
qq String QQ 号
status Byte 0=已拒绝, 1=已通过, 2=待审核
description String 申请备注
createTime String 申请时间（ISO 8601）
regionCode Long 地区邮政编码
regionFullName String 地区全称（如"北京市"）
operatorId Integer 操作员 ID
operatorUsername String 操作员用户名
operatorNickname String 操作员昵称
totalScore Integer 答题总分
emailActive Boolean 邮箱是否已验证