# 通用约定

所有 `/api` 接口共用以下约定: 统一响应结构、错误码、限速与缓存。接口无需鉴权, 支持 CORS 跨域, 可以在浏览器前端直接调用。

## 统一响应格式

```json
{
  "code": 200,
  "data": {},
  "msg": "success"
}
```

| 字段 | 说明 |
| --- | --- |
| `code` | 业务状态码, `200` 为成功; 失败时等于对应的 HTTP 状态码 |
| `data` | 业务数据, 结构见各接口文档; 失败时为 `null` |
| `msg` | 成功为 `success`, 失败为中文错误说明, 仅供排查, 不要用来做分支判断 |

> 以 `code` 判定成败, 不要只看 HTTP 状态码; 响应里的可选字段在无数据时省略, 按开放式对象解析, 缺字段不应报错。

## 错误码

| code | 含义 | 处理建议 |
| --- | --- | --- |
| `400` | 参数错误: IP 格式无效、ASN 超出范围、代理检测缺少 `enableProxyDetection` | 修正请求, 不要重试 |
| `404` | 资源不存在 (如 ASN 在 RIPEstat 无记录) | 不要重试 |
| `408` | 上游查询超时 (BGP) | 稍后重试 |
| `429` | 超过限速 | 按 `Retry-After` 退避后重试 |
| `500` | 服务内部错误 | 指数退避重试, 持续出现请反馈 |
| `503` | 上游暂不可用 (BGP) | 稍后重试 |

## 限速

按客户端 IP 独立计数, 每个接口一分钟一个固定窗口:

| 接口 | 限额 |
| --- | --- |
| `/api/query` | 600 次 / 分钟 |
| `/api/bgp/*` | 60 次 / 分钟 |
| `/api/proxy-detection` | 30 次 / 分钟 |
| `/` 及其他接口 | 300 次 / 分钟 |

每个响应都带限速头:

| 响应头 | 说明 |
| --- | --- |
| `X-RateLimit-Limit` | 窗口内允许的总次数 |
| `X-RateLimit-Remaining` | 本窗口剩余次数 |
| `X-RateLimit-Reset` | 窗口重置时间, RFC 3339 格式 |
| `Retry-After` | 仅超限时返回, 建议等待的秒数 |

超限时 HTTP 状态码为 `429`, 响应体多一个 `retryAfter` 字段 (秒):

```json
{
  "code": 429,
  "data": null,
  "msg": "请求过于频繁，请稍后重试",
  "retryAfter": 46
}
```

- 批量查询请在本地做缓存、去重和节流, 不要逐条裸打
- 命中 `429` 按 `Retry-After` 等待后再试, 不要立即重发
- 可以读 `X-RateLimit-Remaining` 实时掌握剩余次数, 接近 0 时主动放慢

## 缓存

接口响应带 `Cache-Control`, 调用方可以按它在本地缓存:

| 接口 | `Cache-Control` |
| --- | --- |
| `/api/query` | `public, max-age=300` |
| `/api/bgp/:asn` | `public, max-age=1800` |
| `/api/proxy-detection` | `public, max-age=60` |
| `/` (纯文本 IP) | `no-store` |

同一 IP 的归属信息短时间内基本不变, 批量场景建议按 IP 缓存至少 5 分钟。
