367 lines
10 KiB
Markdown
367 lines
10 KiB
Markdown
# 搜索接口文档
|
||
|
||
## 接口概述
|
||
|
||
提供网站内容搜索功能，支持模糊搜索和精确搜索，多关键字搜索，以及自定义搜索字段。
|
||
|
||
| 属性 | 值 |
|
||
| ---- | ------------------ |
|
||
| 接口地址 | `/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` 判断是否显示"加载更多"按钮
|
||
|