cwd/docs/api/overview.md

API 概览

基础信息

• Base URL：https://your-worker.workers.dev 或你的自定义域名
• 数据格式：JSON
• 字符编码：UTF-8

所有 API 均为 RESTful 风格，无会话 Cookie，认证全部通过 Authorization 请求头完成。

版本信息

当前后端版本号在根路径返回：

GET /

成功时返回 HTML，其中包含类似文案：

CWD 评论部署成功，当前版本 v0.0.1

说明：

• 当前 API 路径未在 URL 中显式区分版本（如 /v1），版本号仅通过根路径展示。
• 后续若引入不兼容变更，建议通过自定义域名路径前缀或 Worker 路由实现接口版本化，例如：
  • https://comments-api.example.com/v1
  • https://api.example.com/comments/v1

鉴权方式

公开接口与管理员接口的鉴权要求不同：

• 公开接口（Public API）
  • /api/comments
  • /api/config/comments
  • 默认无需认证，可直接访问。
• 管理员接口（Admin API）
  • 路径前缀：/admin/*
  • 除 /admin/login 外，其余接口都需要携带管理员 Token。

管理员接口需要使用 Bearer Token 认证：

Authorization: Bearer <token>

Token 通过登录接口获取，有效期为 24 小时，服务端会在 KV 中存储会话信息并在每次请求时进行校验。

统一字段与约定

虽然当前实现没有使用统一的 success 包装字段，但存在一些通用约定：

• 错误响应：

  • 始终包含 message 字段，描述错误原因。
  • HTTP 状态码用于表达错误类型（例如 400/401/403/429/500）。

• 列表类响应：

  • 使用 data + pagination 结构：

    {
      "data": [ /* 列表数据 */ ],
      "pagination": {
        "page": 1,
        "limit": 20,
        "total": 5,
        "totalCount": 100
      }
    }
    

• 单项结果或配置类响应：

  • 直接返回对象，例如：

    {
      "email": "admin@example.com"
    }
    

• 操作类响应（创建、更新、删除）：

  • 一般返回 { "message": "说明文本" }。

HTTP 状态码

常见状态码及含义如下：

状态码	说明	典型场景
200	请求成功	正常查询、操作成功
400	请求参数错误	缺少必填字段、格式不正确等
401	未授权	未携带 Token 或 Token 失效
403	禁止访问	登录失败次数过多导致 IP 被暂时封禁
404	资源不存在（当前未显式使用）	预留给未来可能的资源不存在场景
429	请求过于频繁	评论频率超过限制（默认同一 IP 10 秒内只能评论一次）
500	服务器内部错误	未捕获异常、数据库错误等

具体到每个接口的详细请求 / 响应体和错误码，请参考：

• 公开 API
• 管理员 API