wushu/lib/services/document/搜索api.md

搜索接口文档

接口概述

提供网站内容搜索功能，支持模糊搜索和精确搜索，多关键字搜索，以及自定义搜索字段。

属性	值
接口地址	/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	更新时间

---

响应格式

响应结构

{
    "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

---

响应示例

成功响应

{
    "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
        }
    }
}

指定返回字段响应（精简数据）

{
    "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": {...}
    }
}

错误响应

{
    "code": -1,
    "msg": "搜索关键词不能为空",
    "data": null
}

频率限制响应

{
    "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)

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)

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 判断是否显示"加载更多"按钮