接口接入指南

1. 访问首页

   在浏览器中打开首页，浏览推荐接口并查看调用趋势。

2. 注册账号

   点击导航栏「注册」按钮创建账号；后续可调用需要认证的接口。

3. 获取令牌

   使用 /api/v1/auth/login 获取访问令牌（Bearer Token）。

4. 发起调用

   在任意接口详情页在线调试，或直接在客户端携带 Bearer Token 调用。

本系统采用 JWT 双令牌机制：短时效访问令牌 + 服务端刷新令牌。

• 访问令牌：有效期 15 分钟，通过 Authorization: Bearer <token> 或 Cookie 传递。
• 刷新令牌：有效期 30 天，仅存服务端哈希，支持轮换与撤销。

登录流程

POST /api/v1/auth/login
{
  "email": "user@example.com",
  "password": "YourPassword"
}

# 成功响应（含 HttpOnly Cookie）
{
  "ok": true,
  "data": {
    "access_token": "...",
    "refresh_token": "...",
    "expires_in": 900,
    "refresh_expires_in": 2592000
  }
}

刷新令牌

POST /api/v1/auth/refresh
{
  "refresh_token": "..."
}

# 返回新的一对令牌（Cookie 自动更新）

退出登录

POST /api/v1/auth/logout
{
  "refresh_token": "..."
}

# 撤销刷新令牌，清除 Cookie

所有 API 统一 JSON 格式，带 request_id 便于追踪。

成功响应

{
  "ok": true,
  "data": { ... },
  "request_id": "abc123..."
}

失败响应

{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "参数校验失败",
    "details": { ... }
  },
  "request_id": "abc123..."
}

UNAUTHORIZED

未登录或令牌无效（401）

FORBIDDEN

权限不足（403）

NOT_FOUND

资源不存在（404）

BAD_REQUEST

参数校验失败（422）

TOKEN_EXPIRED

访问令牌过期（401）

REFRESH_TOKEN_EXPIRED

刷新令牌过期（401）

REFRESH_TOKEN_REUSED

检测到令牌重放，已注销全部会话（401）

ACCOUNT_LOCKED

登录失败次数过多，已锁定（429）

TOO_MANY_REQUESTS

超过限流阈值（429）

CSRF_TOKEN_MISMATCH

CSRF 校验失败（419）

默认每分钟每个 IP 最多 60 次请求（可通过环境变量调整）。超限返回 429 TOO_MANY_REQUESTS，并在响应头中给出 Retry-After。