docs: 更新文档链接、添加favicon并完善API文档
- 更新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
This commit is contained in:
anghunk
@@ -1,150 +1,433 @@
|
||||
# 管理员 API
|
||||
|
||||
所有管理员 API 都需要在请求头中携带 Bearer Token：
|
||||
管理员接口用于登录后台、查看和管理评论、配置邮件通知和评论显示设置。
|
||||
|
||||
除登录接口外，所有管理员接口都需要在请求头中携带 Bearer Token。
|
||||
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
## 管理员登录
|
||||
Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
获取管理员 Token。
|
||||
本节按 OpenAPI 风格描述每个接口的请求 / 响应结构，并补充鉴权和错误码说明。
|
||||
|
||||
### 请求
|
||||
## POST /admin/login
|
||||
|
||||
```http
|
||||
POST /admin/login
|
||||
Content-Type: application/json
|
||||
```
|
||||
管理员登录，获取后续调用其他管理员接口所需的临时 Token。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/admin/login`
|
||||
- 鉴权：不需要
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"name": "admin@example.com",
|
||||
"password": "your_password"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| --------- | ------ | ---- | ------------------ |
|
||||
| `name` | string | 是 | 管理员登录名 |
|
||||
| `password`| string | 是 | 管理员登录密码 |
|
||||
|
||||
管理员登录名和密码由后端环境变量控制，字段为：
|
||||
|
||||
- `ADMIN_NAME`
|
||||
- `ADMIN_PASSWORD`
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"expiresIn": 604800
|
||||
"key": "f6e1e0e3-3c9b-4a24-9e88-3b1f709f1e4a"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 获取评论管理列表
|
||||
前端需要将 `data.key` 作为 Token 存储（例如 LocalStorage），并在后续请求中通过 `Authorization: Bearer <key>` 携带。
|
||||
|
||||
获取所有评论列表（包括待审核的评论）。
|
||||
### 错误与风控
|
||||
|
||||
### 请求
|
||||
- 登录失败（用户名或密码错误）：
|
||||
|
||||
```http
|
||||
GET /admin/comments/list?page={page}&pageSize={pageSize}&status={status}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
- 状态码：`401`
|
||||
|
||||
### 参数
|
||||
```json
|
||||
{
|
||||
"message": "Invalid username or password",
|
||||
"failedAttempts": 3
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| -------- | ------ | ---- | ----------------------------------- |
|
||||
| page | number | 否 | 页码，默认 1 |
|
||||
| pageSize | number | 否 | 每页数量，默认 20 |
|
||||
| status | string | 否 | 状态筛选：pending/approved/rejected |
|
||||
- 登录失败次数过多导致 IP 被封禁：
|
||||
|
||||
### 响应示例
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "IP is blocked due to multiple failed login attempts"
|
||||
}
|
||||
```
|
||||
|
||||
- 内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /admin/comments/list
|
||||
|
||||
获取评论列表，用于后台管理页面展示。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/comments/list`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ------- | ----- | ------- | ---- | ----------------------- |
|
||||
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||||
|
||||
说明：
|
||||
|
||||
- 当前实现中每页固定大小为 `10`，暂不支持 `pageSize` 或状态过滤。
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"comments": [
|
||||
{
|
||||
"id": 1,
|
||||
"path": "/blog/hello-world",
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"content": "很棒的文章！",
|
||||
"parent_id": null,
|
||||
"status": "pending",
|
||||
"created_at": "2026-01-13T10:00:00Z"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"pubDate": "2026-01-13T10:00:00Z",
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"postSlug": "/blog/hello-world",
|
||||
"url": "https://zhangsan.me",
|
||||
"ipAddress": "127.0.0.1",
|
||||
"contentText": "很棒的文章！",
|
||||
"contentHtml": "很棒的文章！",
|
||||
"status": "approved",
|
||||
"avatar": "https://gravatar.com/avatar/..."
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 20
|
||||
"limit": 10,
|
||||
"total": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 更新评论状态
|
||||
### 鉴权错误
|
||||
|
||||
审核评论，更新评论状态。
|
||||
- 未携带 Token 或 Token 失效：
|
||||
|
||||
### 请求
|
||||
- 状态码：`401`
|
||||
|
||||
```http
|
||||
PUT /admin/comments/status
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```json
|
||||
{
|
||||
"message": "Unauthorized"
|
||||
}
|
||||
```
|
||||
|
||||
## PUT /admin/comments/status
|
||||
|
||||
更新评论状态（例如通过 / 拒绝）。
|
||||
|
||||
- 方法：`PUT`
|
||||
- 路径：`/admin/comments/status`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| -------- | ----- | ------ | ---- | -------------------------------- |
|
||||
| `id` | query | number | 是 | 评论 ID |
|
||||
| `status` | query | string | 是 | 评论状态，例如 `approved`、`rejected` |
|
||||
|
||||
当前实现中未对 `status` 值进行枚举校验，但推荐仅使用：
|
||||
|
||||
- `approved`：已通过
|
||||
- `rejected`：已拒绝
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Comment status updated, id: 1, status: approved."
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 缺少参数：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Missing id or status"
|
||||
}
|
||||
```
|
||||
|
||||
- 更新失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Update failed"
|
||||
}
|
||||
```
|
||||
|
||||
## DELETE /admin/comments/delete
|
||||
|
||||
删除指定评论。
|
||||
|
||||
- 方法：`DELETE`
|
||||
- 路径：`/admin/comments/delete`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ---- | ----- | ------ | ---- | ------ |
|
||||
| `id` | query | number | 是 | 评论 ID |
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Comment deleted, id: 1."
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 缺少 ID：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Missing id"
|
||||
}
|
||||
```
|
||||
|
||||
- 删除失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Delete operation failed"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /admin/settings/email
|
||||
|
||||
获取当前通知邮箱配置。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/settings/email`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "admin@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
## PUT /admin/settings/email
|
||||
|
||||
设置通知邮箱，用于接收新评论提醒。
|
||||
|
||||
- 方法：`PUT`
|
||||
- 路径：`/admin/settings/email`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"status": "approved"
|
||||
"email": "admin@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 参数说明
|
||||
### 成功响应
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------ | ------ | ---- | ---------------------------------------- |
|
||||
| id | number | 是 | 评论 ID |
|
||||
| status | string | 是 | 状态：approved（通过）/ rejected（拒绝） |
|
||||
|
||||
### 响应示例
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"message": "评论状态已更新"
|
||||
}
|
||||
"message": "保存成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 删除评论
|
||||
### 错误响应
|
||||
|
||||
删除指定评论。
|
||||
- 邮箱格式不正确：
|
||||
|
||||
### 请求
|
||||
- 状态码：`400`
|
||||
|
||||
```http
|
||||
DELETE /admin/comments/delete?id={id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
```json
|
||||
{
|
||||
"message": "邮箱格式不正确"
|
||||
}
|
||||
```
|
||||
|
||||
### 参数
|
||||
- 服务器错误：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| id | number | 是 | 评论 ID |
|
||||
- 状态码：`500`
|
||||
|
||||
### 响应示例
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /admin/settings/comments
|
||||
|
||||
获取评论配置，例如博主邮箱、徽标和头像前缀等。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/settings/comments`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"message": "评论已删除"
|
||||
}
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "博主",
|
||||
"avatarPrefix": "https://gravatar.com/avatar",
|
||||
"adminEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
字段说明与公开接口 `/api/config/comments` 一致。
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "加载评论配置失败"
|
||||
}
|
||||
```
|
||||
|
||||
## PUT /admin/settings/comments
|
||||
|
||||
更新评论配置。
|
||||
|
||||
- 方法：`PUT`
|
||||
- 路径：`/admin/settings/comments`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "站长",
|
||||
"avatarPrefix": "https://cravatar.cn/avatar",
|
||||
"adminEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| -------------- | ------- | ---- | ------------------------------------------------ |
|
||||
| `adminEmail` | string | 否 | 博主邮箱地址，需为合法邮箱 |
|
||||
| `adminBadge` | string | 否 | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 否 | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||
| `adminEnabled` | boolean | 否 | 是否启用博主标识相关功能 |
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 邮箱格式错误：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "邮箱格式不正确"
|
||||
}
|
||||
```
|
||||
|
||||
- 内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存失败"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -2,47 +2,102 @@
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **Base URL**: `https://your-worker.workers.dev`
|
||||
- **数据格式**: JSON
|
||||
- **字符编码**: UTF-8
|
||||
- **Base URL**：`https://your-worker.workers.dev` 或你的自定义域名
|
||||
- **数据格式**：JSON
|
||||
- **字符编码**：UTF-8
|
||||
|
||||
## 认证方式
|
||||
所有 API 均为 RESTful 风格，无会话 Cookie，认证全部通过 `Authorization` 请求头完成。
|
||||
|
||||
管理员 API 需要使用 Bearer Token 认证：
|
||||
## 版本信息
|
||||
|
||||
当前后端版本号在根路径返回：
|
||||
|
||||
```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 小时。
|
||||
Token 通过登录接口获取，有效期为 24 小时，服务端会在 KV 中存储会话信息并在每次请求时进行校验。
|
||||
|
||||
## 响应格式
|
||||
## 统一字段与约定
|
||||
|
||||
### 成功响应
|
||||
虽然当前实现没有使用统一的 `success` 包装字段，但存在一些通用约定：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": { ... }
|
||||
}
|
||||
```
|
||||
- 错误响应：
|
||||
- 始终包含 `message` 字段，描述错误原因。
|
||||
- HTTP 状态码用于表达错误类型（例如 400/401/403/429/500）。
|
||||
- 列表类响应：
|
||||
- 使用 `data` + `pagination` 结构：
|
||||
|
||||
### 错误响应
|
||||
```json
|
||||
{
|
||||
"data": [ /* 列表数据 */ ],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 5,
|
||||
"totalCount": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "错误信息"
|
||||
}
|
||||
```
|
||||
- 单项结果或配置类响应：
|
||||
- 直接返回对象，例如：
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "admin@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
- 操作类响应（创建、更新、删除）：
|
||||
- 一般返回 `{ "message": "说明文本" }`。
|
||||
|
||||
## HTTP 状态码
|
||||
|
||||
| 状态码 | 说明 |
|
||||
| ------ | ------------ |
|
||||
| 200 | 请求成功 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未授权 |
|
||||
| 403 | 禁止访问 |
|
||||
| 404 | 资源不存在 |
|
||||
| 500 | 服务器错误 |
|
||||
常见状态码及含义如下：
|
||||
|
||||
| 状态码 | 说明 | 典型场景 |
|
||||
| ------ | -------------------------- | ---------------------------------------------------- |
|
||||
| 200 | 请求成功 | 正常查询、操作成功 |
|
||||
| 400 | 请求参数错误 | 缺少必填字段、格式不正确等 |
|
||||
| 401 | 未授权 | 未携带 Token 或 Token 失效 |
|
||||
| 403 | 禁止访问 | 登录失败次数过多导致 IP 被暂时封禁 |
|
||||
| 404 | 资源不存在（当前未显式使用）| 预留给未来可能的资源不存在场景 |
|
||||
| 429 | 请求过于频繁 | 评论频率超过限制（默认同一 IP 10 秒内只能评论一次） |
|
||||
| 500 | 服务器内部错误 | 未捕获异常、数据库错误等 |
|
||||
|
||||
具体到每个接口的详细请求 / 响应体和错误码，请参考：
|
||||
|
||||
- [公开 API](./public.md)
|
||||
- [管理员 API](./admin.md)
|
||||
|
||||
@@ -1,90 +1,262 @@
|
||||
# 公开 API
|
||||
|
||||
## 获取评论列表
|
||||
本节描述无需认证即可访问的公开接口，包括评论获取、评论提交以及评论设置获取。
|
||||
|
||||
获取指定页面的评论列表。
|
||||
遵循 OpenAPI 风格进行组织，包含路径、方法、参数、请求体和响应示例。
|
||||
|
||||
### 请求
|
||||
## GET /api/comments
|
||||
|
||||
```http
|
||||
GET /api/comments?path={path}&page={page}&pageSize={pageSize}
|
||||
```
|
||||
获取指定文章的评论列表。
|
||||
|
||||
### 参数
|
||||
- 方法：`GET`
|
||||
- 路径：`/api/comments`
|
||||
- 鉴权：不需要
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| -------- | ------ | ---- | ----------------- |
|
||||
| path | string | 是 | 页面路径 |
|
||||
| page | number | 否 | 页码，默认 1 |
|
||||
| pageSize | number | 否 | 每页数量，默认 10 |
|
||||
### 查询参数
|
||||
|
||||
### 响应示例
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| -------------- | ------ | ------- | ---- | -------------------------------------------------------------------- |
|
||||
| `post_slug` | query | string | 是 | 文章唯一标识符，与前端配置中的 `postSlug` 保持一致 |
|
||||
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||||
| `limit` | query | integer | 否 | 每页数量，默认 `20`，最大 `50` |
|
||||
| `nested` | query | string | 否 | 是否返回嵌套结构，默认 `'true'` |
|
||||
| `avatar_prefix`| query | string | 否 | 覆盖头像地址前缀，优先级高于服务端设置和前端配置 |
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"comments": [
|
||||
{
|
||||
"id": 1,
|
||||
"path": "/blog/hello-world",
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"content": "很棒的文章！",
|
||||
"parent_id": null,
|
||||
"status": "approved",
|
||||
"created_at": "2026-01-13T10:00:00Z",
|
||||
"avatar": "https://gravatar.com/avatar/..."
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"url": "https://example.com",
|
||||
"contentText": "很棒的文章！",
|
||||
"contentHtml": "很棒的文章！",
|
||||
"pubDate": "2026-01-13T10:00:00Z",
|
||||
"postSlug": "/blog/hello-world",
|
||||
"avatar": "https://gravatar.com/avatar/...",
|
||||
"replies": [
|
||||
{
|
||||
"id": 2,
|
||||
"author": "李四",
|
||||
"email": "lisi@example.com",
|
||||
"url": null,
|
||||
"contentText": "同感！",
|
||||
"contentHtml": "同感！",
|
||||
"pubDate": "2026-01-13T11:00:00Z",
|
||||
"postSlug": "/blog/hello-world",
|
||||
"avatar": "https://gravatar.com/avatar/...",
|
||||
"parentId": 1,
|
||||
"replyToAuthor": "张三"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 10
|
||||
"limit": 20,
|
||||
"total": 1,
|
||||
"totalCount": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 提交评论
|
||||
说明：
|
||||
|
||||
提交新评论。
|
||||
- 当 `nested=true`（默认）时，接口返回的是“根评论列表”，每条根评论包含其 `replies`。
|
||||
- 当 `nested=false` 时，接口返回扁平列表，所有评论都在 `data` 中，`replies` 为空。
|
||||
|
||||
### 请求
|
||||
### 错误响应
|
||||
|
||||
```http
|
||||
POST /api/comments
|
||||
Content-Type: application/json
|
||||
```
|
||||
- 缺少 `post_slug`：
|
||||
|
||||
### 请求体
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "post_slug is required"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
## POST /api/comments
|
||||
|
||||
提交新评论或回复。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/api/comments`
|
||||
- 鉴权：不需要
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ---------------------------- |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体（Request Body）
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "/blog/hello-world",
|
||||
"post_slug": "/blog/hello-world",
|
||||
"post_title": "博客标题，可选",
|
||||
"post_url": "https://example.com/blog/hello-world",
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"url": "https://zhangsan.me",
|
||||
"content": "很棒的文章！",
|
||||
"parent_id": null
|
||||
"parent_id": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 参数说明
|
||||
#### 字段说明
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------- | ------ | ---- | ----------------------- |
|
||||
| path | string | 是 | 页面路径 |
|
||||
| author | string | 是 | 评论者昵称 |
|
||||
| email | string | 是 | 评论者邮箱 |
|
||||
| content | string | 是 | 评论内容 |
|
||||
| parent_id | number | 否 | 父评论 ID（回复时使用） |
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ------------ | ------ | ---- | ------------------------------------------------------------ |
|
||||
| `post_slug` | string | 是 | 文章唯一标识符，应与前端组件初始化时的 `postSlug` 值一致 |
|
||||
| `post_title` | string | 否 | 文章标题，用于邮件通知内容 |
|
||||
| `post_url` | string | 否 | 文章 URL，用于邮件通知中的跳转链接 |
|
||||
| `author` | string | 是 | 评论者昵称 |
|
||||
| `email` | string | 是 | 评论者邮箱，需为合法邮箱格式 |
|
||||
| `url` | string | 否 | 评论者个人主页或站点地址 |
|
||||
| `content` | string | 是 | 评论内容，内部会过滤 `<script>...</script>` 片段 |
|
||||
| `parent_id` | number | 否 | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论 |
|
||||
|
||||
### 响应示例
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"message": "评论提交成功，等待审核"
|
||||
}
|
||||
"message": "Comment submitted. Awaiting moderation."
|
||||
}
|
||||
```
|
||||
|
||||
当前实现中评论会直接以 `approved` 状态写入数据库，后续如引入人工审核可在实现中调整为“待审核”状态。
|
||||
|
||||
### 错误响应与限流
|
||||
|
||||
- 请求体缺失或字段类型错误：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "无效的请求体"
|
||||
}
|
||||
```
|
||||
|
||||
- 缺少必填字段示例：
|
||||
|
||||
- `post_slug` 为空：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "post_slug 必填"
|
||||
}
|
||||
```
|
||||
|
||||
- `content` 为空：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "评论内容不能为空"
|
||||
}
|
||||
```
|
||||
|
||||
- `author` 为空：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "昵称不能为空"
|
||||
}
|
||||
```
|
||||
|
||||
- `email` 为空或格式不正确：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "邮箱不能为空"
|
||||
}
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "邮箱格式不正确"
|
||||
}
|
||||
```
|
||||
|
||||
- 评论频率限制：
|
||||
|
||||
- 状态码：`429`
|
||||
- 逻辑：同一 IP 最近一条评论时间在 10 秒内，则拒绝此次请求。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "评论频繁，等10s后再试"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Internal Server Error"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /api/config/comments
|
||||
|
||||
获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/api/config/comments`
|
||||
- 鉴权：不需要
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "博主",
|
||||
"avatarPrefix": "https://gravatar.com/avatar",
|
||||
"adminEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| -------------- | ------- | ------------------------------------------------ |
|
||||
| `adminEmail` | string | 博主邮箱地址，用于在前端展示“博主”标识 |
|
||||
| `adminBadge` | string | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||
| `adminEnabled` | boolean | 是否启用博主标识相关功能 |
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "加载评论配置失败"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user