开放 API 文档 · 废土之后

01 / OVERVIEWGET STARTED

快速开始

API 返回 UTF-8 JSON，只读取网站服务器上的战绩缓存，不会因接口调用直接访问或写入游戏服务器数据库。当前版本无需 API Key。

AUTH无需鉴权PUBLIC ACCESS

FORMATJSONUTF-8

VERSIONv1STABLE PATH

CORS默认开放ORIGIN *

读取 API 索引

GET https://feitu.mchyt.net/api/v1

RESPONSE / JSON

{
  "success": true,
  "data": {
    "name": "废土之后战绩 API",
    "version": "v1",
    "endpoints": {
      "player": "/api/v1/player/{name-or-uuid}",
      "leaderboard": "/api/v1/leaderboard?metric=extract_value&limit=20&page=1",
      "status": "/api/v1/status"
    },
    "leaderboard_metrics": [
      "extract_value", "kills", "kd",
      "rounds", "playtime", "level"
    ]
  },
  "meta": { "request_id": "c845cc5f4ecb2f62" }
}

DATA DELAY

游戏插件默认每约 120 秒写入源库；网站白天每 30 秒、夜间每 60 秒同步，因此接口数据不是瞬时实时数据。

02 / LIVE TESTREAL REQUEST

在线测试台

点击按钮会从当前浏览器向本站真实 API 发起 HTTPS GET 请求。右侧控制台会显示实际 HTTP 状态、耗时、限流余量和服务器返回的 JSON。

基础接口

NO PARAMETERS

测试 API 路由是否可访问，或检查网站缓存同步健康状态。

玩家战绩

PLAYER LOOKUP

玩家名或 UUID

排行榜

LEADERBOARD

排行榜指标

每页数量

页码

LIVE RESPONSE等待请求

GET — 点击左侧测试按钮开始请求

耗时—

剩余限额—

限额上限—

缓存策略—

{
  "message": "选择一个接口并点击测试按钮。"
}

REAL TRAFFIC

这里发送的是真实请求，会计入当前 IP 每分钟 60 次的默认限额。请勿连续快速点击；触发 429 后应等待 Retry-After 指定的时间。

03 / PLAYERPLAYER RECORD

查询玩家

使用玩家名或 UUID 查询单个玩家。玩家名支持 1—32 位英文字母、数字和下划线；UUID 支持带连字符或不带连字符的形式。

GET https://feitu.mchyt.net/api/v1/player/PlayerOne

路径中的玩家名或 UUID 应进行 URL 编码。也可使用下面的查询参数形式。

GET https://feitu.mchyt.net/api/v1/player?name=PlayerOne

参数

参数	位置	类型	说明
name-or-uuid 必填	路径	string	玩家名、32 位 UUID 或标准带连字符 UUID。
name 二选一	查询参数	string	路径形式之外的玩家名查询方式。
uuid 二选一	查询参数	string	路径形式之外的 UUID 查询方式。

成功响应示例

200 OK / JSON

{
  "success": true,
  "data": {
    "identity": {
      "uuid": "0f47d2c6-7b9e-4c4b-8a12-6bc0eaadef4a",
      "name": "PlayerOne"
    },
    "combat": {
      "kills": 42,
      "deaths": 18,
      "kd": 2.33,
      "rounds": 67
    },
    "operation": {
      "total_playtime_ms": 128760000,
      "total_playtime_hours": 35.77,
      "total_extract_value": 986430,
      "total_loss": 215600,
      "avg_loss": 3217.91
    },
    "progression": {
      "experience": 4280,
      "level": 16,
      "money": 125800,
      "black_market_level": 4,
      "storage_level": 4,
      "medical_producer_level": 2,
      "food_producer_level": 3,
      "drink_producer_level": 2
    },
    "ranks": {
      "extract_value": 3,
      "kills": 8,
      "kd": 5
    },
    "freshness": {
      "source_updated_at_ms": 1786710841163,
      "source_updated_at": "2026-08-14T12:34:01+00:00",
      "cached_at": "2026-08-14 20:34:21.274"
    }
  },
  "meta": {
    "request_id": "c845cc5f4ecb2f62",
    "data_source": "website_mysql_cache"
  }
}

NAME FIELD

identity.name 是游戏插件最近一次写入的玩家名。若游戏服源表名称异常，API 会如实返回缓存值。

04 / LEADERBOARDPUBLIC RANKING

查询排行榜

选择一个榜单指标并进行分页查询。排行榜按指标方向排序，同值时按玩家名升序排列。

GET https://feitu.mchyt.net/api/v1/leaderboard?metric=extract_value&limit=20&page=1

查询参数

参数	类型	默认值	说明
metric	string	extract_value	排行榜指标，见下方指标表。
limit	integer	20	每页返回数量，默认最大 100；服务器配置可调整上限。
page	integer	1	页码，从 1 开始；超过末页时返回末页。

可用指标

metric	含义	方向	入榜条件
extract_value	累计成功带出价值	高 → 低	无
kills	累计击杀	高 → 低	无
kd	KD 比率	高 → 低	至少死亡 10 次
rounds	累计行动局数	高 → 低	无
playtime	累计行动时长，单位毫秒	高 → 低	无
level	玩家等级	高 → 低	无

成功响应示例

200 OK / JSON

{
  "success": true,
  "data": {
    "metric": {
      "key": "extract_value",
      "label": "累计带出价值",
      "direction": "desc",
      "minimums": []
    },
    "players": [
      {
        "rank": 1,
        "uuid": "0f47d2c6-7b9e-4c4b-8a12-6bc0eaadef4a",
        "name": "PlayerOne",
        "value": 986430,
        "kills": 42,
        "deaths": 18,
        "kd": 2.33,
        "rounds": 67,
        "level": 16
      }
    ]
  },
  "meta": {
    "request_id": "44f08fe9f4b3ac11",
    "page": 1,
    "per_page": 20,
    "pages": 4,
    "total": 68,
    "data_source": "website_mysql_cache"
  }
}

05 / STATUSSYNC HEALTH

同步状态

读取缓存玩家数量及最近同步状态，可用于监控页面、机器人健康检查或外部服务降级判断。接口不会公开数据库错误详情。

GET https://feitu.mchyt.net/api/v1/status

200 OK / JSON

{
  "success": true,
  "data": {
    "healthy": true,
    "cached_players": 68,
    "last_success_at": "2026-08-14T12:34:11+00:00",
    "last_source_update_at": "2026-08-14T12:34:01+00:00",
    "last_mode": "incremental",
    "last_duration_ms": 192
  },
  "meta": {
    "request_id": "a4aeb09b675f9ca8"
  }
}

HEALTHY

healthy 表示最近成功同步是否仍在站点配置的有效时间范围内；默认超过 300 秒未成功同步即为 false。

06 / RESPONSESRESPONSE SHAPE

通用响应结构

成功响应使用 success: true，业务数据放在 data 中；失败响应使用 success: false，错误信息放在 error 中。多数响应会携带可用于日志定位的 request_id。

SUCCESS

{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "c845cc5f4ecb2f62"
  }
}

ERROR

{
  "success": false,
  "error": {
    "code": "player_not_found",
    "message": "未找到该玩家。"
  },
  "meta": {
    "request_id": "c845cc5f4ecb2f62"
  }
}

07 / EXAMPLESCLIENT CODE

调用示例

下面的示例均查询玩家 PlayerOne。生产环境中应同时检查 HTTP 状态码与响应中的 success 字段。

CURL / SHELL

curl --fail-with-body --silent --show-error \
  --header "Accept: application/json" \
  "https://feitu.mchyt.net/api/v1/player/PlayerOne"

JAVASCRIPT / FETCH

const endpoint = "https://feitu.mchyt.net/api/v1/player/PlayerOne";

const response = await fetch(endpoint, {
  headers: { Accept: "application/json" }
});
const payload = await response.json();

if (!response.ok || !payload.success) {
  throw new Error(payload.error?.message ?? `HTTP ${response.status}`);
}

console.log(payload.data.identity.name, payload.data.combat.kd);

PHP / CURL

<?php

$url = 'https://feitu.mchyt.net/api/v1/player/PlayerOne';
$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Accept: application/json'],
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 10,
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}
curl_close($curl);

$payload = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400 || !($payload['success'] ?? false)) {
    throw new RuntimeException($payload['error']['message'] ?? 'API 请求失败');
}

echo $payload['data']['identity']['name'];

08 / LIMITSRATE & CACHE

限流与缓存

默认情况下，每个来源 IP 每分钟最多请求 60 次。服务端在每个 API 响应中返回限流信息；达到上限后返回 HTTP 429。

响应头	说明	示例
X-RateLimit-Limit	当前一分钟窗口的请求上限。	60
X-RateLimit-Remaining	当前窗口内剩余请求次数。	53
X-RateLimit-Reset	限流窗口重置时间，Unix 秒级时间戳。	1786713000
Retry-After	仅在触发 429 时返回，表示建议等待秒数。	27
Cache-Control	正常 GET 默认允许客户端缓存 20 秒。	public, max-age=20

CLIENT POLICY

机器人或网页应缓存成功结果，并在收到 429 后遵循 Retry-After，不要立即循环重试。

09 / ERRORSFAILURE HANDLING

状态码与错误码

接口使用标准 HTTP 状态码。客户端不应只判断 JSON 是否可解析，还应检查 HTTP 状态与 success。

HTTP	常见 error.code	说明
200	—	请求成功。
404	player_not_found endpoint_not_found	没有对应玩家，或接口路径不存在。
405	method_not_allowed	使用了 GET、OPTIONS 之外的方法。
422	invalid_player invalid_parameter	玩家标识格式或排行榜指标无效。
429	rate_limited	超过当前 IP 的请求频率上限。
503	api_disabled service_unavailable	API 被关闭，或战绩服务暂时不可用。

错误处理建议

REQUEST ID

记录 HTTP 状态码、error.code 和 meta.request_id。反馈接口故障时提供请求 ID，可更快对应服务器日志。

APIDOCUMENT

快速开始

读取 API 索引

在线测试台

查询玩家

参数

成功响应示例

查询排行榜

查询参数

可用指标

成功响应示例

同步状态

通用响应结构

调用示例

限流与缓存

状态码与错误码

错误处理建议