10 KiB
诗词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
返回示例
{
"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"
}
}
注意事项
- 浏览次数统计：只要接口成功返回 data，该站点的日、月、总浏览次数均会 +1。
- 朝代对应：数据库字段 alias，标签对应 keywords（支持模糊匹配）。
- 多个值分隔：用英文逗号分隔，不要混用中文逗号。
- 点赞/取消点赞：基于 IP 进行限制，同一 IP 对同一站点切换状态。
- like 是无值参数：只需在 URL 中包含 &like 或 ?like 即可，无需赋值。
- 频率限制：每个 IP 每秒最多请求 2 次，超出将返回
{"code":429, "msg":"请求过于频繁，请稍后再试"}。 - 接口未做严格的频率限制，但建议合理调用。
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 |
返回格式
{
"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
返回格式
{
"code": 0,
"msg": "success",
"data": {
"total": 8,
"dynasties": [
"先秦",
"汉代",
"唐代",
"宋代",
"元代",
"明代",
"清代",
"暂无朝代"
]
}
}
4. 排行榜接口 (/apilist.php)
接口说明
获取诗词排行榜信息，包括点赞排行、浏览排行等。
请求方式: GET
请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|
| type | string | 否 | 排行类型：like(点赞), hits(浏览) |
| period | string | 否 | 时间周期：day(日), month(月), total(总) |
| limit | int | 否 | 返回数量，默认10 |
返回格式
{
"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
返回格式
{
"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 | 服务器内部错误 |
通用响应格式
所有接口都遵循统一的响应格式：
{
"code": 0, // 状态码
"msg": "success", // 提示信息
"data": {} // 具体数据，成功时返回
}
开发建议
- 错误处理：检查
code字段，非0时处理错误信息 - 频率控制：避免短时间内大量请求，建议每秒不超过2次
- 缓存策略：对于不常变化的数据（如朝代列表），建议本地缓存
- 分页处理：搜索接口支持分页，合理设置每页数量
- 字段验证：传入参数前进行基本验证
Flutter客户端使用示例
使用HttpClient
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:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
鸿蒙:
"requestPermissions": [
{"name": "ohos.permission.INTERNET"},
{"name": "ohos.permission.GET_NETWORK_INFO"}
]
最后更新时间: 2026-03-21 API版本: v1.0