217 lines
5.4 KiB
Markdown
217 lines
5.4 KiB
Markdown
# 统计 API 接口文档
|
||
|
||
## 概述
|
||
|
||
获取网站统计信息的 API 接口，返回分类数量、收录数量、热度统计等数据。
|
||
|
||
## 基础信息
|
||
|
||
- **接口地址**: `https://yy.vogov.cn/api/app/stats.php`
|
||
- **请求方式**: GET
|
||
- **返回格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
- **支持跨域**: 是（`Access-Control-Allow-Origin: *`）
|
||
|
||
## 请求参数
|
||
|
||
无需任何参数，直接 GET 请求即可。
|
||
|
||
## 返回示例
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"count_category": 3,
|
||
"count_site": 15807,
|
||
"count_apply": 14,
|
||
"count_apply_reject": 3,
|
||
"count_article": 2,
|
||
"count_article_category": 4,
|
||
"count_notice": 2,
|
||
"count_link": 3,
|
||
"count_tags": 131,
|
||
"cumulative_hits": "16887",
|
||
"cumulative_likes": "272",
|
||
"top_hits_day": {
|
||
"id": "7559",
|
||
"name": "除却天边月，没人知。人有悲欢离合，月有阴晴圆缺，此事古难全。"
|
||
},
|
||
"top_hits_month": {
|
||
"id": "461",
|
||
"name": "人有悲欢离合，月有阴晴圆缺，此事古难全。"
|
||
},
|
||
"top_hits_total": {
|
||
"id": "1",
|
||
"name": "井鱼焉知身在渊，错把方寸作世间"
|
||
},
|
||
"top_like": {
|
||
"id": "5876",
|
||
"name": "世间无比酒，天下有名楼。"
|
||
},
|
||
"build_time": "2026-03-04"
|
||
},
|
||
"timestamp": 1774977191
|
||
}
|
||
```
|
||
|
||
## 返回字段说明
|
||
|
||
### 基础字段
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| --------- | ------- | ------ |
|
||
| ok | boolean | 请求是否成功 |
|
||
| data | object | 统计数据对象 |
|
||
| timestamp | int | 服务器时间戳 |
|
||
|
||
### data 对象字段
|
||
|
||
#### 数量统计
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ------------------------ | --- | ---- |
|
||
| count\_category | int | 项目 |
|
||
| count\_site | int | 收录诗句 |
|
||
| count\_apply | int | 审核中 |
|
||
| count\_apply\_reject | int | 已拒绝 |
|
||
| count\_article | int | 每日一句 |
|
||
| count\_article\_category | int | 文章分类 |
|
||
| count\_notice | int | 推送 |
|
||
| count\_link | int | 开发者 |
|
||
| count\_tags | int | 分类标签 |
|
||
|
||
#### 热度统计
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ----------------- | ------ | ------ |
|
||
| cumulative\_hits | string | 累计热度次数 |
|
||
| cumulative\_likes | string | 累计点赞数量 |
|
||
|
||
#### 热门内容
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ---------------- | ----------- | ------ |
|
||
| top\_hits\_day | object/null | 当天热门诗句 |
|
||
| top\_hits\_month | object/null | 本月热门诗句 |
|
||
| top\_hits\_total | object/null | 历史最热诗句 |
|
||
| top\_like | object/null | 最高点赞诗句 |
|
||
|
||
#### 热门内容对象
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ---- | ------ | ----- |
|
||
| id | string | 诗句 ID |
|
||
| name | string | 诗句内容 |
|
||
|
||
#### 其他
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ----------- | ------ | ------------------- |
|
||
| build\_time | string | 建站时间（格式：YYYY-MM-DD） |
|
||
|
||
## 错误返回
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": "错误信息"
|
||
}
|
||
```
|
||
|
||
## 调用示例
|
||
|
||
### JavaScript (Fetch)
|
||
|
||
```javascript
|
||
fetch('https://yy.vogov.cn/api/app/stats.php')
|
||
.then(response => response.json())
|
||
.then(data => {
|
||
if (data.ok) {
|
||
console.log('已收录诗句：', data.data.count_site);
|
||
console.log('当天热门：', data.data.top_hits_day.name);
|
||
}
|
||
})
|
||
.catch(error => console.error('Error:', error));
|
||
```
|
||
|
||
### Flutter (Dart)
|
||
|
||
```dart
|
||
import 'package:http/http.dart' as http;
|
||
import 'dart:convert';
|
||
|
||
Future<StatsData?> getStats() async {
|
||
final response = await http.get(
|
||
Uri.parse('https://yy.vogov.cn/api/app/stats.php'),
|
||
);
|
||
|
||
if (response.statusCode == 200) {
|
||
final data = json.decode(response.body);
|
||
if (data['ok'] == true) {
|
||
return StatsData.fromJson(data['data']);
|
||
}
|
||
}
|
||
return null;
|
||
}
|
||
|
||
class StatsData {
|
||
final int countSite;
|
||
final String cumulativeHits;
|
||
final TopContent? topHitsDay;
|
||
|
||
StatsData({
|
||
required this.countSite,
|
||
required this.cumulativeHits,
|
||
this.topHitsDay,
|
||
});
|
||
|
||
factory StatsData.fromJson(Map<String, dynamic> json) {
|
||
return StatsData(
|
||
countSite: json['count_site'],
|
||
cumulativeHits: json['cumulative_hits'],
|
||
topHitsDay: json['top_hits_day'] != null
|
||
? TopContent.fromJson(json['top_hits_day'])
|
||
: null,
|
||
);
|
||
}
|
||
}
|
||
|
||
class TopContent {
|
||
final String id;
|
||
final String name;
|
||
|
||
TopContent({required this.id, required this.name});
|
||
|
||
factory TopContent.fromJson(Map<String, dynamic> json) {
|
||
return TopContent(id: json['id'], name: json['name']);
|
||
}
|
||
}
|
||
```
|
||
|
||
## 数据来源
|
||
|
||
数据来源于以下数据库表：
|
||
|
||
| 表名 | 说明 |
|
||
| ---------------------- | ----- |
|
||
| pre\_category | 分类表 |
|
||
| pre\_site | 收录诗句表 |
|
||
| pre\_apply | 申请收录表 |
|
||
| pre\_article | 文章表 |
|
||
| pre\_article\_category | 文章分类表 |
|
||
| pre\_notice | 公告表 |
|
||
| pre\_link | 友情链接表 |
|
||
|
||
## 注意事项
|
||
|
||
1. **缓存建议**：统计数据变化频率较低，建议客户端缓存 5-10 分钟
|
||
2. **空值处理**：热门内容字段可能为 `null`，请做好空值判断
|
||
3. **跨域支持**：接口已配置 CORS，支持前端直接调用
|
||
4. **数据类型**：`cumulative_hits` 和 `cumulative_likes` 返回的是字符串类型
|
||
|
||
## 更新日志
|
||
|
||
- **v1.0.14** (2026-03-30): 新增统计 API 接口
|
||
|