520kiss/wushu
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ui细节优化

Browse Source
This commit is contained in:
Developer
2026-04-01 04:45:33 +08:00
parent 6517a78c7e
commit 79f7269319
23 changed files with 3299 additions and 885 deletions
Download Patch File Download Diff File Expand all files Collapse all files

366
lib/services/document/搜索api.md Normal file
View File

@@ -0,0 +1,366 @@
# 搜索接口文档
## 接口概述
提供网站内容搜索功能，支持模糊搜索和精确搜索，多关键字搜索，以及自定义搜索字段。
| 属性 | 值 |
| ---- | ------------------ |
| 接口地址 | `/searchs.php` |
| 请求方式 | GET / POST |
| 响应格式 | JSON |
| 编码 | UTF-8 |
***
## 请求参数
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
| -------------- | ------ | --- | ------------------ | --------------------------------- |
| keyword | string | ✅ 是 | - | 搜索关键词，支持多关键字（用空格或逗号分隔） |
| mode | string | 否 | fuzzy | 搜索模式：`fuzzy`（模糊搜索）或 `exact`（精确搜索） |
| page | int | 否 | 1 | 页码，最小值 1 |
| size | int | 否 | 20 | 每页条数，范围 1-100 |
| fields | string | 否 | name,url,introduce | 搜索字段，多个用逗号分隔 |
| return\_fields | string | 否 | 全部字段 | 返回字段，多个用逗号分隔，可减少数据传输 |
| truncate | int | 否 | 1 | 是否截取长文本：`1` 截取，`0` 返回完整内容 |
### 可用搜索字段
| 字段名 | 说明 |
| --------- | ------- |
| name | 精选诗句 |
| url | 诗人 《标题》 |
| introduce | 译文 |
| keywords | 标签 |
| alias | 朝代 |
| drtime | 原文 |
### 可用返回字段 (return\_fields)
| 字段名 | 类型 | 说明 |
| ------------ | ------ | ------- |
| id | int | 记录ID |
| name | string | 精选诗句 |
| url | string | 诗人 《标题》 |
| alias | string | 朝代 |
| keywords | string | 标签 |
| introduce | string | 译文 |
| drtime | string | 原文 |
| like | int | 点赞数 |
| hits\_total | int | 总访问量 |
| hits\_month | int | 月访问量 |
| hits\_day | int | 日访问量 |
| star | int | 星标数 |
| tui | int | 推荐数 |
| time | string | 时间 |
| create\_time | string | 创建时间 |
| update\_time | string | 更新时间 |
***
## 响应格式
### 响应结构
```json
{
"code": 0,
"msg": "success",
"data": {
"keyword": "搜索关键词",
"mode": "搜索模式",
"fields": ["搜索字段数组"],
"results": [结果数组],
"pagination": {分页信息},
"stats": {统计信息}
}
}
```
### 状态码说明
| code | 说明 |
| ---- | ----------- |
| 0 | 请求成功 |
| -1 | 参数错误（关键词为空） |
| -2 | 搜索失败（服务器错误） |
| 429 | 请求过于频繁 |
### 结果对象 (results)
| 字段 | 类型 | 说明 |
| ------------ | ------ | --------------- |
| id | int | 记录ID |
| name | string | 精选诗句 |
| url | string | 网站链接 |
| alias | string | 朝代 |
| keywords | string | 标签 |
| introduce | string | 译文（超过100字符自动截取） |
| drtime | string | 原文 |
| like | int | 点赞数 |
| hits\_total | int | 总访问量 |
| hits\_month | int | 月访问量 |
| hits\_day | int | 日访问量 |
| star | int | 星标数 |
| tui | int | 推荐数 |
| time | string | 时间 |
| create\_time | string | 创建时间 |
| update\_time | string | 更新时间 |
### 分页信息 (pagination)
| 字段 | 类型 | 说明 |
| ------------- | ---- | ------ |
| current\_page | int | 当前页码 |
| page\_size | int | 每页条数 |
| total\_count | int | 总记录数 |
| total\_pages | int | 总页数 |
| has\_next | bool | 是否有下一页 |
| has\_prev | bool | 是否有上一页 |
### 统计信息 (stats)
| 字段 | 类型 | 说明 |
| --------------- | ------ | ------ |
| search\_time | string | 搜索时间 |
| keyword\_length | int | 关键词字符数 |
| result\_count | int | 当前页结果数 |
***
## 请求示例
### 1. 基本搜索
```
GET /searchs.php?keyword=春天
```
### 2. 多关键字搜索
```
GET /searchs.php?keyword=春天 友情
```
### 3. 精确搜索
```
GET /searchs.php?keyword=春晓&mode=exact
```
### 4. 自定义字段搜索
```
GET /searchs.php?keyword=唐代&fields=alias,keywords
```
### 5. 分页搜索
```
GET /searchs.php?keyword=测试&page=2&size=10
```
### 6. POST 请求
```
POST /searchs.php
Content-Type: application/x-www-form-urlencoded
keyword=春天&mode=fuzzy&page=1&size=20&fields=name,introduce
```
### 7. 指定返回字段（减少数据传输）
```
GET /searchs.php?keyword=春天&return_fields=id,name,keywords,alias
```
### 8. 返回完整内容（不截取）
```
GET /searchs.php?keyword=春天&truncate=0
```
### 9. 组合使用（高效查询）
```
GET /searchs.php?keyword=春天&fields=keywords&return_fields=id,name,keywords,alias&truncate=0
```
***
## 响应示例
### 成功响应
```json
{
"code": 0,
"msg": "success",
"data": {
"keyword": "春天",
"mode": "fuzzy",
"fields": ["name", "url", "introduce"],
"return_fields": ["id", "name", "url", "alias", "keywords", "introduce", "drtime", "like", "hits_total", "hits_month", "hits_day", "star", "tui", "time", "create_time", "update_time"],
"truncate": 1,
"results": [
{
"id": 1,
"name": "春晓",
"url": "刘禹锡《酬乐天扬州初逢席上见赠》",
"alias": "唐代",
"keywords": "春天,孟浩然",
"introduce": "春眠不觉晓，处处闻啼鸟...",
"drtime": "巴山楚水凄凉地，二十三年弃置身。怀旧空吟闻笛赋，到乡翻似烂柯人。沉舟侧畔千帆过，病树前头万木春。今日听君歌一曲，暂凭杯酒长精神。",
"like": 15,
"hits_total": 120,
"hits_month": 50,
"hits_day": 5,
"star": 10,
"tui": 8,
"time": "",
"create_time": "2024-01-01 10:00:00",
"update_time": "2024-01-01 12:00:00"
}
],
"pagination": {
"current_page": 1,
"page_size": 20,
"total_count": 1,
"total_pages": 1,
"has_next": false,
"has_prev": false
},
"stats": {
"search_time": "2024-03-14 20:17:00",
"keyword_length": 2,
"result_count": 1
}
}
}
```
### 指定返回字段响应（精简数据）
```json
{
"code": 0,
"msg": "success",
"data": {
"keyword": "春天",
"mode": "fuzzy",
"fields": ["keywords"],
"return_fields": ["id", "name", "keywords", "alias"],
"truncate": 0,
"results": [
{
"id": 1,
"name": "春晓",
"keywords": "春天,孟浩然,唐诗,五言绝句",
"alias": "唐代"
}
],
"pagination": {...},
"stats": {...}
}
}
```
### 错误响应
```json
{
"code": -1,
"msg": "搜索关键词不能为空",
"data": null
}
```
### 频率限制响应
```json
{
"code": 429,
"msg": "搜索过于频繁，请5秒后再试"
}
```
***
## 注意事项
1. **关键词要求**：必须提供搜索关键词，否则返回错误
2. **多关键字**：模糊搜索支持多关键字，用空格或逗号分隔，任一关键字匹配即返回
3. **字段限制**：只能搜索预定义的字段，无效字段将被忽略
4. **分页限制**：每页最多100条记录，超过限制将自动调整为100
5. **安全处理**：所有输入都会进行安全转义，防止SQL注入
6. **简介截取**：`truncate=1` 时简介字段自动截取到100字符，`truncate=0` 返回完整内容
7. **频率限制**：每个 IP 每 10 秒最多搜索 10 次，超出返回 429 错误
8. **性能优化**：使用 `return_fields` 指定需要的字段，减少数据传输和服务器资源消耗
***
## App 集成建议
### 请求封装示例 (Swift)
```swift
func search(keyword: String,
mode: String = "fuzzy",
page: Int = 1,
size: Int = 20,
fields: String = "name,url,introduce",
returnFields: String = "",
truncate: Int = 1) async throws -> SearchResponse {
var params = [
"keyword": keyword,
"mode": mode,
"page": "\(page)",
"size": "\(size)",
"fields": fields,
"truncate": "\(truncate)"
]
if !returnFields.isEmpty {
params["return_fields"] = returnFields
}
return try await request(endpoint: "/searchs.php", params: params)
}
```
### 请求封装示例 (Kotlin)
```kotlin
suspend fun search(
keyword: String,
mode: String = "fuzzy",
page: Int = 1,
size: Int = 20,
fields: String = "name,url,introduce",
returnFields: String = "",
truncate: Int = 1
): SearchResponse {
val params = mutableMapOf(
"keyword" to keyword,
"mode" to mode,
"page" to page.toString(),
"size" to size.toString(),
"fields" to fields,
"truncate" to truncate.toString()
)
if (returnFields.isNotEmpty()) {
params["return_fields"] = returnFields
}
return request(endpoint = "/searchs.php", params = params)
}
```
### 错误处理建议
- 检测 `code == 429` 时，提示用户稍后重试
- 检测 `code == -1` 时，提示用户输入关键词
- 检测 `code == 0` 时，解析 `data.results` 显示结果列表
- 使用 `pagination.has_next` 判断是否显示"加载更多"按钮