background
2
2
}
E
&
G
u
:
C
k
/
h
)
|
f
c
F
c
H
Z
3
+
e
x
y
%
w
V
3
B
e
@

favicon
favicon
回归终端
 

HTTP API 参考

Reverier-Xu at 2026-04-01 16:00:00 3.8+ R2SPL

欢迎查阅回归终端的 API 参考手册！

此文档记录了 HTTP / WebSocket 接口、字段约定、中间件行为与错误语义。当你需要为回归终端做出代码贡献，或者围绕回归终端开发第三方组件时，可以直接把这里当成路由入口索引。

本项目欢迎大家踊跃发起代码贡献！希望大家可以一起将其建设为更加优秀的训练与竞赛平台。

同时，本项目作者并不介意其他平台开发者借鉴本平台的架构思路、参考实现代码等等，也十分欢迎一起交流开发。

作为开源项目，我们希望这件作品可以以任何形式推动人类社会的小小进步，而非以保守封闭的态度来争夺市场。即便它后续没落了，至少在架构探索与实现上也能留下一些技术痕迹。

虽然秉承开放的态度，也还请在 复制代码 / 用 AI 提炼代码 时注意遵守本项目的开源协议与附加条款（思路参考不受此限制）。

对于使用本项目进行套壳贩售 / 竞标、违反基于 GPL-3.0 衍生的开源协议规范、在入口设定付费操作、拒绝开源等行为，我们保留追诉的一切权利。

基本约定

Middleware

认证与权限

Public

无需登录即可访问，是否真正放行由 handler 内部逻辑决定。

Guest-aware

路由层不强制登录，调用者身份只影响过滤、脱敏和分支行为。

Basic

需要已登录用户。

Verified

需要已登录且邮箱验证已完成的用户。

Basic + Verified

需要同时通过登录态与邮箱验证检查。

Permission::User

需要平台级用户管理权限。

Permission::Bulletin

需要公告管理权限。

Permission::Calendar

需要日历管理权限。

Permission::Wiki

需要 Wiki 管理权限。

Permission::Game

需要比赛级管理权限，用于镜像仓库等受限资源。

Permission::Host

需要创建与管理比赛的 Host 权限。

Permission::DevOps

需要平台运维权限。

Permission::Statistics

需要平台级统计与日志查看权限。

Statistics | DevOps

需要 Permission::Statistics 或 Permission::DevOps 之一。

Institute Token

依赖原始 Bearer Token 解析出的机构身份，而不是常规用户登录态。

game_access_required

在比赛实体加载后检查当前用户是否可以进入该比赛上下文。

challenge_access_required

在比赛可访问基础上继续检查题目可见性、发布时间与队伍状态。

game_admin_required

要求当前用户拥有 Permission::Game 且属于比赛管理员列表。

Internal Hook Auth

要求请求来自本机，并命中缓存中的一次性 session 与 auth 校验值。

数据装载

prepare_user_info

将当前 token 对应的用户实体加载到上下文，供 handler 直接使用。

prepare_data!(institute)

根据路径参数加载机构实体，并写入 tracing 上下文。

prepare_data!(user)

根据路径参数加载目标用户实体，并写入 tracing 上下文。

prepare_data!(game)

根据路径参数加载比赛实体，并写入 tracing 上下文。

prepare_team_info

解析当前用户在目标比赛中的队伍上下文，结果可能为空。

prepare_data!(challenge)

根据路径参数加载题目实体，并写入 tracing 上下文。

prepare_data!(team)

根据路径参数加载目标队伍实体，并写入 tracing 上下文。

prepare_data!(notification)

根据路径参数加载比赛通知实体，并写入 tracing 上下文。

prepare_data!(audit)

根据路径参数加载审核记录实体，并写入 tracing 上下文。

使用方式