速率限制规则

为了保障闪耀船首后端服务的稳定性与高可用性，防止恶意刷取与突发流量冲击，平台对所有开放 API 实施了动态分级速率限制策略（Rate Limiting）。

---

限制策略与分级机制

平台依据接口类型、资源消耗及请求来源实施自适应限流：

• 数据检索类接口：对高频读取类接口（如配装检索、掉宝列表、地图点位等）提供较为宽松的常规配额，满足正常前端交互与机器人速查需求。
• 写入与状态变更接口：对配装发布、地图集创建、用户信息修改等写入操作实施严格的频次保护。
• 敏感与高开销接口：如用户登录、密码重置、验证码请求及服务端动态长图渲染等，配备精准的安全限流窗口，防止暴力破解与算力耗尽。
• 多维度限制：限流基于客户端 IP 地址、用户鉴权 Token 以及 AppID 进行多层级动态计算。

---

响应标头信息

每次调用 API 时，服务端会在 HTTP 响应标头中附带当前时间窗口的配额状态信息：

响应标头	说明
X-RateLimit-Limit	当前时间窗口内允许的最大请求数
X-RateLimit-Remaining	当前时间窗口内剩余的可用请求数
X-RateLimit-Reset	速率限制计数器重置的 Unix 时间戳（秒）

响应标头示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1774932000

---

超出限制时的处理

当请求频次超出平台当前窗口配额时，API 将直接拦截并返回 HTTP 429 Too Many Requests 状态码：

{
  "code": 429,
  "message": "请求过于频繁，请稍后再试",
  "data": {
    "retryAfter": 15
  }
}

此时响应标头中会包含 Retry-After 字段，指示客户端需要等待退避的秒数。

---

客户端最佳接入实践

• 合理利用本地缓存：对于变化频率较低的数据（如游戏图鉴、战事历史档案、指南图卡等），建议客户端在本地维护合理时长的缓存（如 5 分钟至 3 小时），避免重复发送相同请求。
• 实现指数退避重试：当收到 HTTP 429 响应时，应解析 Retry-After 标头并采用指数退避加抖动算法（Exponential Backoff with Jitter）进行重试，切勿立即循环重发。
• 批量与分页请求节流：在拉取分页数据时，建议在连续请求之间加入毫秒级间隔延迟。
• 携带用户认证凭证：登录用户的认证请求通常享有更合理的专属配额，建议在需要持续交互的场景下完成鉴权接入。