9b90f589d5
- 更新widget/README.md中的文档链接 - 在cwd-comments-admin/index.html中添加favicon - 更新docs/.vitepress/config.mjs中的标题和favicon配置 - 在cwd-comments-admin/src/views/LayoutView.vue中添加文档链接 - 全面重写并完善API文档结构，包括overview.md、public.md和admin.md - 更新前端配置文档frontend-config.md和后端配置文档backend-config.md
104 lines
3.2 KiB
Markdown
104 lines
3.2 KiB
Markdown
# API 概览
|
||
|
||
## 基础信息
|
||
|
||
- **Base URL**：`https://your-worker.workers.dev` 或你的自定义域名
|
||
- **数据格式**：JSON
|
||
- **字符编码**：UTF-8
|
||
|
||
所有 API 均为 RESTful 风格，无会话 Cookie，认证全部通过 `Authorization` 请求头完成。
|
||
|
||
## 版本信息
|
||
|
||
当前后端版本号在根路径返回：
|
||
|
||
```http
|
||
GET /
|
||
```
|
||
|
||
成功时返回 HTML，其中包含类似文案：
|
||
|
||
```text
|
||
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 认证：
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
Token 通过登录接口获取，有效期为 24 小时，服务端会在 KV 中存储会话信息并在每次请求时进行校验。
|
||
|
||
## 统一字段与约定
|
||
|
||
虽然当前实现没有使用统一的 `success` 包装字段，但存在一些通用约定：
|
||
|
||
- 错误响应：
|
||
- 始终包含 `message` 字段，描述错误原因。
|
||
- HTTP 状态码用于表达错误类型（例如 400/401/403/429/500）。
|
||
- 列表类响应：
|
||
- 使用 `data` + `pagination` 结构：
|
||
|
||
```json
|
||
{
|
||
"data": [ /* 列表数据 */ ],
|
||
"pagination": {
|
||
"page": 1,
|
||
"limit": 20,
|
||
"total": 5,
|
||
"totalCount": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
- 单项结果或配置类响应：
|
||
- 直接返回对象，例如：
|
||
|
||
```json
|
||
{
|
||
"email": "admin@example.com"
|
||
}
|
||
```
|
||
|
||
- 操作类响应（创建、更新、删除）：
|
||
- 一般返回 `{ "message": "说明文本" }`。
|
||
|
||
## HTTP 状态码
|
||
|
||
常见状态码及含义如下：
|
||
|
||
| 状态码 | 说明 | 典型场景 |
|
||
| ------ | -------------------------- | ---------------------------------------------------- |
|
||
| 200 | 请求成功 | 正常查询、操作成功 |
|
||
| 400 | 请求参数错误 | 缺少必填字段、格式不正确等 |
|
||
| 401 | 未授权 | 未携带 Token 或 Token 失效 |
|
||
| 403 | 禁止访问 | 登录失败次数过多导致 IP 被暂时封禁 |
|
||
| 404 | 资源不存在（当前未显式使用）| 预留给未来可能的资源不存在场景 |
|
||
| 429 | 请求过于频繁 | 评论频率超过限制（默认同一 IP 10 秒内只能评论一次） |
|
||
| 500 | 服务器内部错误 | 未捕获异常、数据库错误等 |
|
||
|
||
具体到每个接口的详细请求 / 响应体和错误码，请参考：
|
||
|
||
- [公开 API](./public.md)
|
||
- [管理员 API](./admin.md)
|