412 lines
10 KiB
Markdown
412 lines
10 KiB
Markdown
# 诗词API接口文档
|
||
|
||
## 概述
|
||
|
||
本文档描述了诗词应用的所有API接口，包括诗词推荐、搜索、点赞、统计等功能。
|
||
|
||
**基础URL**: `https://yy.vogov.cn/api/`
|
||
|
||
---
|
||
|
||
## 1. 诗词推荐接口 (`/pms.php`)
|
||
|
||
### 接口说明
|
||
提供诗词随机推荐、获取指定站点信息及点赞功能，支持朝代、标签多条件筛选。
|
||
|
||
**请求方式**: GET / POST 均可
|
||
|
||
**重要**: 只要接口成功返回 `data` 字段，即会自动增加该站点的浏览次数（日、月、总）。
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `lid` | int | 否 | 点赞ID。传入时直接对该站点执行点赞/取消点赞，返回更新后的信息，并增加浏览次数统计。此时忽略其他所有参数。 |
|
||
| `id` | int | 否 | 站点ID。返回该站点的完整信息（不点赞），可与 `like` 组合实现同时点赞。 |
|
||
| `like` | 标志 | 否 | 无值参数。若存在，则对本次请求返回的站点（通过 `id` 指定或随机推荐）执行点赞/取消点赞。可与 `id`、`dyn`、`tag` 组合。 |
|
||
| `dyn` | string | 否 | 朝代，多个用英文逗号分隔，例如 `宋代,唐代`。条件为"或"，即满足任一朝代。 |
|
||
| `tag` | string | 否 | 标签，多个用英文逗号分隔，例如 `友情,柳树`。条件为"或"，即满足任一标签。 |
|
||
|
||
### 优先级说明
|
||
- `lid` > `id` > 随机推荐。若同时提供 `lid` 和 `like`，`like` 无效（以 `lid` 为准）。
|
||
- 若不提供任何参数，则从全站随机返回一条。
|
||
- 若同时提供 `dyn` 和 `tag`，则取交集（必须同时满足朝代和标签条件）。
|
||
|
||
### 返回格式
|
||
|
||
始终返回 JSON 格式，包含以下字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `code` | int | 状态码：0 成功，非0 失败 |
|
||
| `msg` | string | 提示信息（如"点赞成功"、"取消点赞"等） |
|
||
| `data` | object | 站点完整信息 |
|
||
|
||
### data 对象字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | int | 站点ID |
|
||
| `name` | string | 诗词名称/诗句 |
|
||
| `alias` | string | 朝代 |
|
||
| `keywords` | string | 标签（多个用逗号分隔） |
|
||
| `introduce` | string | 译文/介绍 |
|
||
| `drtime` | string | 原文 |
|
||
| `like` | int | 点赞数 |
|
||
| `url` | string | 诗人和<标题> |
|
||
| `tui` | int | 是否推荐（1是0否） |
|
||
| `star` | int | 星级 |
|
||
| `hits_total` | int | 总浏览数 |
|
||
| `hits_month` | int | 月浏览数 |
|
||
| `hits_day` | int | 日浏览数 |
|
||
| `date` | string | 最后统计日期（Y-m-d） |
|
||
| `datem` | string | 最后统计月份（Y-m） |
|
||
| `time` | string | 收录时间 |
|
||
| `create_time` | string | 创建时间 |
|
||
| `update_time` | string | 更新时间 |
|
||
| …… | | 其他数据库字段均返回 |
|
||
|
||
### 示例请求
|
||
|
||
#### 1. 随机推荐（无参数）
|
||
```
|
||
GET /pms.php
|
||
```
|
||
|
||
#### 2. 随机推荐并点赞
|
||
```
|
||
GET /pms.php?like
|
||
```
|
||
|
||
#### 3. 获取指定站点信息（id=5）
|
||
```
|
||
GET /pms.php?id=5
|
||
```
|
||
|
||
#### 4. 获取指定站点信息并点赞（id=5 且 like）
|
||
```
|
||
GET /pms.php?id=5&like
|
||
```
|
||
|
||
#### 5. 按朝代筛选（宋代或唐代）并随机推荐
|
||
```
|
||
GET /pms.php?dyn=宋代,唐代
|
||
```
|
||
|
||
#### 6. 按朝代筛选并点赞（like 标志）
|
||
```
|
||
GET /pms.php?like&dyn=宋代
|
||
```
|
||
|
||
#### 7. 按标签筛选（友情）并点赞
|
||
```
|
||
GET /pms.php?like&tag=友情
|
||
```
|
||
|
||
#### 8. 同时筛选（朝代=宋代 且 标签=友情）并点赞
|
||
```
|
||
GET /pms.php?like&dyn=宋代&tag=友情
|
||
```
|
||
|
||
#### 9. 直接点赞指定站点（lid=5）
|
||
```
|
||
POST /pms.php?lid=5
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "点赞成功",
|
||
"data": {
|
||
"id": 15572,
|
||
"name": "良将不怯死以苟免，烈士不毁节以求生",
|
||
"alias": "暂无朝代",
|
||
"keywords": "三国志",
|
||
"introduce": "优秀的将领不会畏惧死亡而苟且偷生，忠烈之士不会毁坏名节而求得生存。",
|
||
"drtime": "(赏析)此句强调了人的尊严和信仰是不能被牺牲和放弃...",
|
||
"like": 1,
|
||
"tui": 0,
|
||
"star": 4,
|
||
"hits_total": 156,
|
||
"hits_month": 12,
|
||
"hits_day": 3,
|
||
"date": "2026-03-21",
|
||
"datem": "2026-03",
|
||
"create_time": "2026-03-13 06:38:24",
|
||
"update_time": "2026-03-13 21:03:58"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 注意事项
|
||
|
||
1. **浏览次数统计**：只要接口成功返回 data，该站点的日、月、总浏览次数均会 +1。
|
||
2. **朝代对应**：数据库字段 alias，标签对应 keywords（支持模糊匹配）。
|
||
3. **多个值分隔**：用英文逗号分隔，不要混用中文逗号。
|
||
4. **点赞/取消点赞**：基于 IP 进行限制，同一 IP 对同一站点切换状态。
|
||
5. **like 是无值参数**：只需在 URL 中包含 &like 或 ?like 即可，无需赋值。
|
||
6. **频率限制**：每个 IP 每秒最多请求 2 次，超出将返回 `{"code":429, "msg":"请求过于频繁，请稍后再试"}`。
|
||
7. **接口未做严格的频率限制**，但建议合理调用。
|
||
|
||
---
|
||
|
||
## 2. 搜索接口 (`/searchs.php`)
|
||
|
||
**Flutter 客户端**：`lib/utils/http/poetry_api.dart` 中 `PoetryApi.searchPoetry` 已对接本接口；全站搜索 UI 为 `lib/views/active/active_search_page.dart`。
|
||
|
||
### 接口说明
|
||
提供诗词内容搜索功能，支持模糊搜索和精确搜索，多关键字搜索，以及自定义搜索字段。
|
||
|
||
**请求方式**: GET / POST 均可
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `q` | string | 否 | 搜索关键词 |
|
||
| `field` | string | 否 | 搜索字段：name(标题), keywords(标签), introduce(译文) |
|
||
| `page` | int | 否 | 页码，默认1 |
|
||
| `limit` | int | 否 | 每页数量，默认20 |
|
||
|
||
### 返回格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "搜索成功",
|
||
"data": {
|
||
"total": 156,
|
||
"page": 1,
|
||
"limit": 20,
|
||
"list": [
|
||
{
|
||
"id": 123,
|
||
"name": "诗词标题",
|
||
"alias": "唐代",
|
||
"keywords": "友情,离别",
|
||
"introduce": "译文内容...",
|
||
"like": 25,
|
||
"hits_total": 1024
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 示例请求
|
||
|
||
#### 1. 基础搜索
|
||
```
|
||
GET /searchs.php?q=李白
|
||
```
|
||
|
||
#### 2. 按标题搜索
|
||
```
|
||
GET /searchs.php?q=李白&field=name
|
||
```
|
||
|
||
#### 3. 分页搜索
|
||
```
|
||
GET /searchs.php?q=爱情&page=2&limit=10
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 朝代列表接口 (`/dyn.php`)
|
||
|
||
### 接口说明
|
||
获取所有可用的朝代列表。
|
||
|
||
**请求方式**: GET
|
||
|
||
### 返回格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"total": 8,
|
||
"dynasties": [
|
||
"先秦",
|
||
"汉代",
|
||
"唐代",
|
||
"宋代",
|
||
"元代",
|
||
"明代",
|
||
"清代",
|
||
"暂无朝代"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 排行榜接口 (`/apilist.php`)
|
||
|
||
### 接口说明
|
||
获取诗词排行榜信息，包括点赞排行、浏览排行等。
|
||
|
||
**请求方式**: GET
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `type` | string | 否 | 排行类型：like(点赞), hits(浏览) |
|
||
| `period` | string | 否 | 时间周期：day(日), month(月), total(总) |
|
||
| `limit` | int | 否 | 返回数量，默认10 |
|
||
|
||
### 返回格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"top_like": [
|
||
{"id": 123, "name": "诗词标题", "like": 156}
|
||
],
|
||
"top_hits_day": [
|
||
{"id": 456, "name": "诗词标题", "hits_day": 89}
|
||
],
|
||
"top_hits_month": [
|
||
{"id": 789, "name": "诗词标题", "hits_month": 456}
|
||
],
|
||
"top_hits_total": [
|
||
{"id": 101, "name": "诗词标题", "hits_total": 2341}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 网站统计接口 (`/stat.php`)
|
||
|
||
### 接口说明
|
||
获取网站整体统计信息。
|
||
|
||
**请求方式**: GET
|
||
|
||
### 返回格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "网站统计",
|
||
"data": {
|
||
"build_time": "2026-03-13 06:38:24",
|
||
"category": 25,
|
||
"site": 1568,
|
||
"apply": 45,
|
||
"apply_reject": 12,
|
||
"article": 89,
|
||
"article_category": 8,
|
||
"notice": 6,
|
||
"link": 23,
|
||
"top_hits_day": [
|
||
{"id": 123, "name": "诗词标题", "hits_day": 156}
|
||
],
|
||
"top_hits_month": [
|
||
{"id": 456, "name": "诗词标题", "hits_month": 892}
|
||
],
|
||
"top_hits_total": [
|
||
{"id": 789, "name": "诗词标题", "hits_total": 3456}
|
||
],
|
||
"top_like": [
|
||
{"id": 101, "name": "诗词标题", "like": 234}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 通用说明
|
||
|
||
### 错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|------|------|
|
||
| 0 | 成功 |
|
||
| -1 | 数据不存在或参数错误 |
|
||
| 429 | 请求过于频繁 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 通用响应格式
|
||
|
||
所有接口都遵循统一的响应格式：
|
||
|
||
```json
|
||
{
|
||
"code": 0, // 状态码
|
||
"msg": "success", // 提示信息
|
||
"data": {} // 具体数据，成功时返回
|
||
}
|
||
```
|
||
|
||
### 开发建议
|
||
|
||
1. **错误处理**：检查 `code` 字段，非0时处理错误信息
|
||
2. **频率控制**：避免短时间内大量请求，建议每秒不超过2次
|
||
3. **缓存策略**：对于不常变化的数据（如朝代列表），建议本地缓存
|
||
4. **分页处理**：搜索接口支持分页，合理设置每页数量
|
||
5. **字段验证**：传入参数前进行基本验证
|
||
|
||
---
|
||
|
||
## Flutter客户端使用示例
|
||
|
||
### 使用HttpClient
|
||
|
||
```dart
|
||
import 'package:your_app/utils/http/http_client.dart';
|
||
import 'package:your_app/utils/http/poetry_api.dart';
|
||
|
||
// 获取随机诗词
|
||
try {
|
||
final response = await PoetryApi.getRandomPoetry();
|
||
print('诗词标题: ${response.data?.name}');
|
||
print('朝代: ${response.data?.alias}');
|
||
} catch (e) {
|
||
print('获取失败: $e');
|
||
}
|
||
|
||
// 按朝代获取
|
||
final response = await PoetryApi.getRandomPoetry(dynasty: '唐代');
|
||
|
||
// 搜索诗词
|
||
final searchResponse = await PoetryApi.searchPoetry('李白');
|
||
|
||
// 点赞
|
||
if (poetryData?.id != null) {
|
||
await PoetryApi.toggleLike(poetryData!.id);
|
||
}
|
||
```
|
||
|
||
### 网络权限配置
|
||
|
||
确保在 `AndroidManifest.xml` 和 `module.json5` 中配置了网络权限：
|
||
|
||
**Android**:
|
||
```xml
|
||
<uses-permission android:name="android.permission.INTERNET" />
|
||
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
|
||
```
|
||
|
||
**鸿蒙**:
|
||
```json
|
||
"requestPermissions": [
|
||
{"name": "ohos.permission.INTERNET"},
|
||
{"name": "ohos.permission.GET_NETWORK_INFO"}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
*最后更新时间: 2026-03-21*
|
||
*API版本: v1.0*
|