Base URL、请求头、错误体、限流、缓存与 OpenAPI 规范
通用约定
Base URL
| 环境 | 示例 Base URL |
|---|---|
| 本地开发 | https://www.web3base.ai/ |
| 生产 | 部署域名，如 https://example.com |
下文路径均以 站点根 URL（Base URL）为前缀；完整地址 = 站点根 + 路径。
协议与编码
- 协议：HTTPS（生产）；本地可为 HTTP。
- 字符编码：UTF-8。
- 请求体：本文档涉及的公开接口均为 GET，无请求体。
- 响应类型：JSON 接口返回
Content-Type: application/json（除非另有说明）。
通用响应头（公开内容类接口）
多数列表与 Open 接口会包含：
| 响应头 | 含义 |
|---|---|
Cache-Control | 通常为 public, s-maxage=120, stale-while-revalidate=240，便于 CDN / 浏览器缓存 |
限流
路径前缀 /api/open/* 经中间件限流：
| 场景 | 默认配额 |
|---|---|
| 按客户端 IP | 60 次 / 分钟 |
请求头携带合法 X-API-Key | 300 次 / 分钟 |
环境变量（可选）：
| 变量 | 说明 |
|---|---|
OPEN_API_RATE_LIMIT | 每 IP 每分钟上限，默认 60 |
OPEN_API_RATE_LIMIT_KEYED | 带 Key 时每分钟上限，默认 300 |
OPEN_API_KEYS | 逗号分隔的 API Key；与请求头 X-API-Key 比对 |
超限响应示例：
HTTP 429 Too Many Requests
Retry-After: 60{
"error": "Too Many Requests",
"retryAfter": 60
}其他路径（如
/api/twitter/all）当前未统一纳入上述 Open 限流；高并发场景请优先使用/api/open/*并依赖缓存。
错误格式
业务或服务器错误时，JSON 体常见形态：
{
"error": "简短英文或可读说明"
}| HTTP 状态 | 典型含义 |
|---|---|
200 | 成功 |
404 | 资源不存在（如导航分组 slug 不存在） |
429 | Open API 限流 |
500 | 服务端异常 |
机器可读规范（OpenAPI）
- URL：
GET /api/open/spec - 格式：OpenAPI 3.0.x JSON
- 用途：导入 Postman、Insomnia、代码生成或自动化契约校验。
与本文档人工说明互补；以实际部署返回的 /api/open/spec 为准。
多语言 locale
查询参数 locale 建议使用站点支持的语言代码，例如：en、zh-hans、zh-hant 等。非法或未知值将回退为站点默认语言（一般为 en）。