通用约定
本章是全部接口共享的调用约定:基础地址、统一响应包络、错误码、分页、字段单位与请求体上限。各章接口文档中的「注意事项」不再重复这些内容。
基础地址
https://api.hyperfrp.com浏览器端跨域调用默认受限:后端 CORS 白名单仅包含 HyperFRP 自有站点域名,第三方前端如需浏览器直连须先解决跨域(服务端到服务端调用不受 CORS 影响)。全站接入 WAF 防护,恶意或异常高频请求会被拦截。
统一响应包络
除文件下载、图片流等二进制端点外,所有 JSON 响应使用统一包络:
json
{
"code": 0,
"message": "成功",
"data": {}
}code:业务码,0表示成功;失败时与 HTTP 状态码同类(见下表);message:人类可读消息(中文);data:业务数据,成功且有数据时才出现;部分 403 响应(如账户封禁)也会带data;help:极少数 403 响应附带的帮助指引字段,可选。
HTTP 状态码
成功一般是 200;少数创建型操作返回 201(如创建隧道、购买套餐)。失败时 HTTP 状态码与业务码一致(如 code=429 时 HTTP 也是 429)。文件下载端点直接回二进制流与 Content-Disposition,无包络。
响应 JSON 由 SetEscapeHTML(false) 输出:<、>、& 不会被转义成 \u003c 等形式。
错误码表
| code | HTTP | 含义 | 典型场景 |
|---|---|---|---|
| 0 | 200/201 | 成功 | — |
| 400 | 400 | 请求参数错误 | 字段缺失/格式错误、校验失败、业务规则不满足 |
| 401 | 401 | 未授权 | 未携带令牌、JWT 过期、会话失效 |
| 403 | 403 | 禁止访问 | 账户封禁、权限不足、资源不属于自己的 |
| 404 | 404 | 资源不存在 | 隧道/节点/公告等 ID 不存在或不可见 |
| 408 | 408 | 请求超时 | 请求体读取超时 |
| 409 | 409 | 资源冲突 | 端口/域名被占用等唯一性冲突 |
| 413 | 413 | 请求体过大 | 上传超限 |
| 429 | 429 | 请求过于频繁 | 触发限流(见下表) |
| 500 | 500 | 服务器内部错误 | — |
| 503 | 503 | 服务暂不可用 | 依赖(数据库/Redis)不可用 |
请求体与上传上限
| 类型 | 上限 | 适用 |
|---|---|---|
| JSON 请求体 | 2 MB | 所有 JSON 接口(全局 io.LimitReader) |
| 头像上传 | 2 MiB | PUT /api/users/profile/avatar |
| 壁纸上传 | 10 MiB | POST /api/users/profile/wallpaper |
| 实名照片 | 10 MiB | POST /api/users/profile/verify/manual |
上传接口使用 multipart/form-data,字段名见各接口文档;超限返回 413。
字段单位与格式约定
- 流量/字节数:一律为整数字节(
trafficInBytes、remainingTrafficBytes等),前端自行格式化; - 带宽:用户组带宽为 kbps 整数(
bandwidthInKbps/bandwidthOutKbps); - 时间:RFC 3339 字符串(如
2026-09-19T12:34:56+08:00);「周期」类字段(period)按interval参数可为YYYY-MM-DD(天)、YYYY-MM-DDTHH(小时)、YYYY-MM(月); - 分页:通用形态为
data.list[]+total+page+pageSize;个别接口使用自定义形态(隧道搜索为proxies[]+pagination{total,page,pageSize,totalPages},审计日志为logs[]+totalLogs),以各接口文档为准;节点历史类接口的数值为普通数字。
请求追踪
每个响应携带 X-Request-ID 头。客户端可自带合法值([a-zA-Z0-9._-],≤128 字符)以对齐自己的调用链,非法值会被服务端静默替换为 UUID。该 ID 会写入服务端结构化日志,报障时提供它可精确定位。
频率限制
| 范围 | 说明 | 触发后表现 |
|---|---|---|
| 登录 | 同一登录标识有频率限制,成功登录后计数清零 | 429 |
| 邮箱验证码 | 同一「用途 + 邮箱」60 秒间隔 | 429 |
| WebRTC 节点探针 | 每用户 20 次/分钟 | 429 |
其余接口无专用限流中间件,但全站 WAF 防护(含频率控制)照常生效;触发限流的响应均为统一包络 {"code":429,"message":"..."}。
安全防护
全站请求经过 WAF 防护(频率控制、注入与攻击特征拦截等),被拦截时返回统一错误,持续高频请求会被限流或临时封禁。防护策略细节不对外公开,客户端只需保证请求语义正常即可。