17c31d7a1b
- 将大型API文档拆分为多个分类子文档 - 更新文档内容，添加新的API接口说明 - 修复文档中的格式问题和错别字 - 添加反馈文档和Github链接 - 优化侧边栏结构，支持不同路径的独立配置
139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
# 访问统计
|
||
|
||
访问统计接口用于获取页面访问数据、浏览趋势等信息。
|
||
|
||
所有接口都需要在请求头中携带 Bearer Token。
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
## 1.1 获取访问统计概览
|
||
|
||
```
|
||
GET /admin/analytics/overview
|
||
```
|
||
|
||
用于管理后台「访问统计」页面展示整体访问数据，包括总 PV、总页面数以及最近 30 天的访问趋势。
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/admin/analytics/overview`
|
||
- 鉴权：需要（Bearer Token）
|
||
|
||
**查询参数**
|
||
|
||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||
| -------- | ----- | ------ | ---- | ------------------------------------------ |
|
||
| `domain` | query | string | 否 | 按域名筛选访问数据，传入域名，如 `example.com` |
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"totalPv": 1000,
|
||
"totalPages": 50,
|
||
"last30Days": [
|
||
{
|
||
"date": "2026-01-15",
|
||
"total": 20
|
||
},
|
||
{
|
||
"date": "2026-01-16",
|
||
"total": 25
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| -------------- | ------------------- | ------------------------------------- |
|
||
| `totalPv` | number | 总访问量（PV） |
|
||
| `totalPages` | number | 总页面数 |
|
||
| `last30Days` | Array\<DailyStat\> | 最近 30 天的每日访问数（按自然日聚合） |
|
||
| `last30Days[].date` | string (YYYY-MM-DD) | 日期，UTC 时间格式化后的自然日 |
|
||
| `last30Days[].total` | number | 当日访问总数 |
|
||
|
||
**错误响应**
|
||
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "获取访问统计概览失败"
|
||
}
|
||
```
|
||
|
||
## 1.2 获取页面访问统计
|
||
|
||
```
|
||
GET /admin/analytics/pages
|
||
```
|
||
|
||
用于管理后台「访问统计」页面展示各个页面的访问明细，支持按 PV 排序或最新访问排序。
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/admin/analytics/pages`
|
||
- 鉴权：需要（Bearer Token）
|
||
|
||
**查询参数**
|
||
|
||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||
| -------- | ----- | ------ | ---- | ------------------------------------------ |
|
||
| `domain` | query | string | 否 | 按域名筛选访问数据，传入域名，如 `example.com` |
|
||
| `order` | query | string | 否 | 排序方式，`pv`（按访问量排序，默认）或 `latest`（最新访问） |
|
||
|
||
说明：
|
||
|
||
- 当前实现中固定返回前 20 条数据
|
||
- `order=pv`：按访问量降序排序，访问量相同时按最后访问时间降序排序
|
||
- `order=latest`：按最后访问时间降序排序，访问时间相同时按访问量降序排序
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"postSlug": "https://example.com/blog/hello-world",
|
||
"postTitle": "Hello World",
|
||
"postUrl": "https://example.com/blog/hello-world",
|
||
"pv": 100,
|
||
"lastVisitAt": 1737593600000
|
||
},
|
||
{
|
||
"postSlug": "https://example.com/about",
|
||
"postTitle": "关于我",
|
||
"postUrl": "https://example.com/about",
|
||
"pv": 50,
|
||
"lastVisitAt": 1737593500000
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ------------- | ------ | -------------------------- |
|
||
| `postSlug` | string | 文章唯一标识符 |
|
||
| `postTitle` | string \| null | 文章标题 |
|
||
| `postUrl` | string \| null | 文章 URL |
|
||
| `pv` | number | 访问量（PV） |
|
||
| `lastVisitAt` | number \| null | 最后访问时间戳（毫秒） |
|
||
|
||
**错误响应**
|
||
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "获取页面访问统计失败"
|
||
}
|
||
```
|