# 搜索接口文档

## 接口概述

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

| 属性   | 值                  |
| ---- | ------------------ |
| 接口地址 | `/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` 判断是否显示"加载更多"按钮