KukeMC 公共 API 接入指南

范围与使用约定

本指南介绍 13 个 GET 公共 HTTP 接口，供调用方读取公开内容、状态和排行榜。接口访问应遵守服务端权限、部署策略及适用协议；能够阅读本指南不代表获得额外访问权限。

本指南是静态接入说明，未进行业务测试、联网请求或服务验收。请求路径的尾斜杠、参数类型和约束均应按具体接口说明使用。实际部署的序列化、可用性和边界表现尚未验证，不能将模型声明当作成功保证。

本指南所列请求无请求体，支持匿名读取，无需发送身份凭据；表单详情仅面向已发布内容。

示例域名 https://api.example.invalid 仅为占位，无法用于实际接入。请从服务提供方的授权渠道取得真实地址；所有示例均未执行。

三个已声明响应模型为 PublicNews、PublicChangelog、PublicForm。接入时请分别检查字段类型、必填、可空与默认值；未声明结构的内容不应自行假定为固定字段集合。

其他成功响应及未声明的错误响应保持自由 schema，不生成推测的成功样例或统一 code/data/message 信封。错误可能为 400、404、422 或 500，具体条件见各接口。未捕获错误不保证固定 JSON 结构。

nullable 不等于字段可省略，必填与可空应分别阅读。部署版本的响应兼容性未核验；表单题目 schema 与更新日志 content 元素的自由定义不构成附加字段验证契约。

新闻、更新日志及公开表单列表的 skip/limit，以及等级榜的 limit，没有声明 HTTP 层上下界。请使用常规非负偏移和合理条数；这不是新增服务端约束。

13 个公开契约

方法	路径	公开分类	用途
GET	`/api/status`	状态与监测	获取 API 状态
GET	`/api/categories`	内容与分类	获取动态分类
GET	`/api/website/news/`	内容与分类	获取公开新闻列表
GET	`/api/website/changelog/`	内容与分类	获取公开更新日志
GET	`/api/forms/public`	公开表单	获取公开表单列表
GET	`/api/forms/{id_or_slug}`	公开表单	获取公开表单详情
GET	`/api/server/kitbattle/leaderboard/{type}`	游戏排行榜	获取 KitBattle 排行榜
GET	`/api/playerlist/grouped`	在线玩家	获取按服务器分组的玩家列表
GET	`/api/qq/playerlist`	在线玩家	获取玩家名单文本
GET	`/api/servers/status/all`	状态与监测	获取全部服务器状态
GET	`/api/servers/status/{server_id}`	状态与监测	获取单个服务器状态
GET	`/api/level/leaderboard`	游戏排行榜	获取等级排行榜
GET	`/api/verification/status/{username}`	玩家认证	获取玩家公开认证状态

GET /api/status

匿名读取，无请求参数和请求体。成功状态为 HTTP 200，仅用于 API 可达性确认，不代表所有依赖或游戏服务器健康。只读。未声明固定响应模型，不将自由 schema 扩写为推测的成功结构。

GET /api/categories

匿名读取，无请求参数和请求体。HTTP 200 返回分类列表，按 id 升序；无发布状态过滤，无记录时为空列表。只读。未声明固定响应模型；服务异常可能返回 500，错误正文不保证统一。

GET /api/website/news/

匿名读取，无请求体。skip 默认为 0，limit 默认为 20，均为可选整数，未声明 HTTP 层上下界；负数或超大值的具体结果未验证。仅返回 is_published=true 的新闻，按 created_at 降序，HTTP 200 为 PublicNews 数组，不含分页总数。reactions 为各表情计数，comments_count 仅统计已审核评论；user_selected_reactions 默认空数组、reaction_users 默认空对象，不提供按身份个性化结果。只读；参数类型不合法通常为 422，服务或响应兼容性异常可能为 500。

参数	位置	必填	类型	声明默认值
`skip`	query	否	integer	`0`
`limit`	query	否	integer	`20`

GET /api/website/changelog/

匿名读取，无请求体。skip 默认为 0，limit 默认为 20，均为可选整数，未声明 HTTP 层上下界；特殊边界值的具体结果未验证。仅返回 is_published=true 的更新日志，按 created_at 降序，HTTP 200 为 PublicChangelog 数组，不含分页总数。content 的元素未声明固定结构，不推测各元素的字段。只读；参数类型不合法通常为 422，服务或响应兼容性异常可能为 500。

参数	位置	必填	类型	声明默认值
`skip`	query	否	integer	`0`
`limit`	query	否	integer	`20`

GET /api/forms/public

匿名读取，无请求体。skip 默认为 0，limit 默认为 20，均为可选整数，未声明 HTTP 层上下界。先选 status=published 的表单，按创建时间降序并分页，再排除尚未开始或已经结束的项；因此一页可能少于 limit，甚至为空，并非先按时间过滤再分页。时间比较采用 UTC+8 的无时区时间口径，边界以服务端为准。HTTP 200 为 PublicForm 数组，每项计算 submission_count；require_login 不限制列表可见性。只读；类型错误通常为 422，服务、时间或响应兼容性异常可能为 500。

参数	位置	必填	类型	声明默认值
`skip`	query	否	integer	`0`
`limit`	query	否	integer	`20`

GET /api/forms/{id_or_slug}

本接口支持匿名读取已发布内容，无请求体且无需发送身份凭据。id_or_slug 为必填字符串，未声明长度或 slug 格式限制；纯数字先按数字 ID 查找，未找到时再按原字符串 slug 查找。匿名仅可读取 status=published 的表单；不存在或不可公开时为 404，提示分别为 Form not found 或 Form not available。require_login、start_time、end_time 不限制详情可见性，不能据此推断是否可提交。HTTP 200 为 PublicForm；详情不重新计算 submission_count，该值通常为默认 0，不应当作实时提交数。静态 /api/forms/public 优先匹配，slug 为 public 的表单可用数字 ID 读取。只读；特殊数字字符转换或服务、响应兼容性问题可能为 500。

参数	位置	必填	类型	声明默认值
`id_or_slug`	path	是	string	`未声明默认值`

GET /api/server/kitbattle/leaderboard/{type}

匿名读取，无请求体。type 必填，仅接受 kills、deaths、exp、coins、kd；其他值为 400（Invalid leaderboard type）。period 默认 total，仅 weekly、monthly 使用周期统计，其他字符串按累计统计；page 默认 1，服务端将小于 1 的值调整为 1；limit 默认 10，服务端调整到 1～50。search 可省略或为 null，非空值按玩家名进行包含匹配，不去除首尾空白。HTTP 200 含 data 列表及 pagination，分页信息含 total、page、limit、total_pages；榜单项含 name、value、rank、exp、kills、deaths、coins、kd、position。value 为所选指标，kd 为小数，其他指标为整数；其余统计字段仍为累计值，kd 字段也为累计 KD。周期值为累计值减周期起点，仅纳入当前周期匹配者，负增量不截断；KD 分母为零时取击杀数或周期击杀增量。按 value 降序，并列无固定次级顺序；不搜索时 position 为当前分页位置，搜索时尝试全局名次并可能回退列表位置。周期依服务端本地日期，未承诺统一结果快照。只读；整数类型错误通常为 422，服务或数值处理异常可能为 500。未声明固定响应模型，不新增结构化成功 schema。

参数	位置	必填	类型	声明默认值
`type`	path	是	string	`未声明默认值`
`period`	query	否	string	`未声明默认值`
`page`	query	否	integer	`1`
`limit`	query	否	integer	`10`
`search`	query	否	string / null	`null`

GET /api/playerlist/grouped

匿名读取，无请求参数和请求体。HTTP 200 提供 servers、total、lastUpdate；每个服务器分组提供 server、count、players，玩家仅投影 name、uuid、ping，不透传其他字段。缺少服务器名称时归入“未知服务器”，分组按 count 降序、server 字典序排列。name、uuid、ping 未声明固定 JSON 类型，name/uuid 缺省为空字符串，ping 可为 null；延迟值可从不同字段回退，部分回退可能忽略 0。total 为合并名单的行数，可能包含重复或占位项，没有新鲜度过滤，不等于实时去重在线人数。lastUpdate 未声明固定类型，可能为时间字符串、null 或原更新时间值。名单不可用时可能为空；其他异常可能为 500，错误分支含空分组、total=0、lastUpdate=null 及 error 文本。只读；不新增固定成功 schema。

GET /api/qq/playerlist

匿名读取，无请求参数和请求体。HTTP 200 的实际业务响应为 text/plain，展示主名单的行数及逐行玩家名称，不与其他名单合并；占位项也可能计入人数，因此不是实时去重在线人数。名单不可用时可返回 404 纯文本；名称信息缺失或其他异常可返回 500 纯文本。只读，未声明固定响应模型。调用方应按文本读取，不应强制解析为 JSON；错误响应也可能是纯文本。

GET /api/servers/status/all

匿名读取，无请求参数和请求体。HTTP 200 返回服务器状态数组，按 server_id 升序，项含 server_id、display_name、group_name、last_seen、ttl_seconds、online。last_seen 为 ISO 时间字符串加 Z 或 null；ttl_seconds 取状态记录值，缺省口径为 20 秒。online 根据当前 UTC 时间与 last_seen 的差值不超过 TTL 判断，缺少 last_seen 时为 false；这是心跳时间口径，不是主动连通性检测。过期记录仍可返回，并标记相应在线状态。只读；服务异常可能为 500，无统一错误正文承诺；未声明固定成功 schema。

GET /api/servers/status/{server_id}

匿名读取，无请求体。server_id 为必填字符串，精确匹配且不去除首尾空白，未声明长度限制。HTTP 200 返回单个服务器状态，字段与 /api/servers/status/all 的单项一致：server_id、display_name、group_name、last_seen、ttl_seconds、online；last_seen 为 ISO 时间字符串加 Z 或 null，TTL 缺省口径为 20 秒，缺少心跳时 online=false。在线值是心跳时间口径，不是主动连通性检测。未找到时为 404（error 文本为 Not Found），服务异常可能为 500。静态 /api/servers/status/all 优先匹配，不会作为 server_id 查询。只读；未声明固定成功 schema。

参数	位置	必填	类型	声明默认值
`server_id`	path	是	string	`未声明默认值`

GET /api/level/leaderboard

匿名读取，无请求体。limit 为可选整数，默认为 50，未声明 HTTP 层上下界；负数或超大值的具体结果未验证。HTTP 200 返回榜单数组，项含 username、level、total_xp；按 total_xp 降序，level 根据当前经验值计算，无记录时为空数组，并列无固定次级顺序。只读，不创建或更新等级记录。参数类型错误通常为 422，服务异常可能为 500。未声明固定响应模型，不新增结构化成功 schema。

参数	位置	必填	类型	声明默认值
`limit`	query	否	integer	`50`

GET /api/verification/status/{username}

匿名读取，无查询参数和请求体。username 为必填字符串，未声明长度或账号格式约束。HTTP 200 提供 is_verified、verification_type、platform_label：玩家不存在或未认证时表示未认证，平台字段为 null；已认证时提供平台代码及显示标签，未知平台的标签使用原平台值。不存在玩家不返回 404。仅公开认证标记，不返回认证链接、申请状态或拒绝原因。只读；服务异常可能为 500，未声明固定响应模型，不新增结构化成功 schema。

参数	位置	必填	类型	声明默认值
`username`	path	是	string	`未声明默认值`

请求示意（仅占位，未执行）

以上仅展示常规请求方式，不包含真实业务数据或成功返回样例。玩家名称、表单标识与服务器标识应替换为合法的授权业务输入。

文本响应接入注意

GET /api/qq/playerlist 的正常业务响应是 text/plain，调用方应读取文本而非强制解析 JSON。错误响应也可能为纯文本，不应假定所有响应具有相同媒体类型或固定错误结构。

使用边界

本指南仅说明所列公共读取契约，不更改服务端行为，也不承诺接口在所有部署中均可用。自由 schema、静态模型、分页默认值和示例请求都不是业务测试或成功保证。请检查实际响应的 HTTP 状态与媒体类型，并按接口说明处理数据为空、时间口径差异、并列排名和参数边界。

静态检查的 0 命中仅表示在检查覆盖范围内未发现相应字面值，不是完备 DLP 或“无秘密”保证，也不代表业务测试、服务可用性或安全验收通过。实际接入仍应遵守服务提供方的权限与适用协议。

范围与使用约定#

13 个公开契约#

GET /api/status#

GET /api/categories#

GET /api/website/news/#

GET /api/website/changelog/#

GET /api/forms/public#

GET /api/forms/{id_or_slug}#

GET /api/server/kitbattle/leaderboard/{type}#

GET /api/playerlist/grouped#

GET /api/qq/playerlist#

GET /api/servers/status/all#

GET /api/servers/status/{server_id}#

GET /api/level/leaderboard#

GET /api/verification/status/{username}#

请求示意（仅占位，未执行）#

文本响应接入注意#

使用边界#