# 成语搜索关键词怎么写才准？部分匹配 / 分页技巧
> 接口：成语词典（apiCode=2964） · 接入点：搜索成语(2964-1) · 是否免费：是 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：开发者、搜索功能设计者 · 阅读时间：约 5 分钟
## 核心要点
- `keyword` 支持**部分匹配**：传片段（如「株」）也能命中含该片段的成语。
- `page` 控制翻页；分页时用 `allPages` / `allNum` 判断何时停止。
- `keyword` 为空或拼写有误会导致 `allNum` 为 0，需做好空结果处理。
## Why：关键词写不好，体验就差
搜索是用户接触成语词典的第一入口。关键词怎么传，直接决定召回质量：传完整成语只能精确命中，传片段能联想召回，但片段太短可能命中过多。本文讲清匹配行为与分页技巧，帮你把搜索框做得好用。
## What：参数速览
| 参数 | 必填 | 说明 |
|------|------|------|
| `keyword` | 是 | 搜索关键字，支持部分匹配 |
| `page` | 否 | 查询页码，默认 1 |
返回分页字段：`maxResult`(当前页条数上限)、`currentPage`、`allNum`(总数)、`allPages`(总页数)。
## How：匹配与分页实战
### 部分匹配示例
```python
import requests
APPKEY = "YOUR_APPKEY"
def search(keyword, page=1):
r = requests.get("https://route.showapi.com/2964-1",
params={"appKey": APPKEY, "keyword": keyword, "page": str(page)},
timeout=10)
return r.json()["showapi_res_body"]
# 传片段「株」也能命中「守株待兔」
print([it["word"] for it in search("株")["list"]])
# 传完整「守株待兔」精确命中
print([it["word"] for it in search("守株待兔")["list"]])
```
### 翻页拉全（直到末页）
```python
def search_all(keyword):
out, page = [], 1
while True:
b = search(keyword, page)
out.extend(b["list"])
if page >= b["allPages"]:
break
page += 1
return out
print("总数:", len(search_all("画")))
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": 0,
"remark": "查询成功！",
"list": [{"word":"画蛇添足","id":"..."},{"word":"画龙点睛","id":"..."}],
"maxResult": 20, "currentPage": 1, "allNum": 2, "allPages": 1
}
}
```
- `allNum` 是命中总数；`allPages` 是总页数。翻页终止条件：`currentPage >= allPages`。
- `maxResult` 表示单页返回条数上限（示例为 20），不是「本页实际条数」。
## 进阶 / 边界
- **空关键词行为**：文档未明确空 `keyword` 的返回约定，实战需实测；建议前端要求至少输入 1 个字符再发起搜索，并对 `allNum == 0` 给出「未找到相关成语」提示。
- **片段过短**：如单字「一」可能召回极多，建议前端对过短输入做引导（如「请输入更具体的片段」）或限制最小长度。
- **分页缓存**：整页结果可按 `keyword+page` 组合缓存（见[缓存策略](https://www.showapi.com/guides/idiom-pagination-cache-2964)）。
## FAQ
**Q：keyword 必须传完整成语吗？**
不必。支持部分匹配，传片段即可召回含该片段的成语。
**Q：为什么有时 allNum 是 0？**
keyword 为空或没有匹配的成语。前端应提示「未找到」，并引导换关键词。
**Q：page 不传会用哪一页？**
默认第 1 页（`page=1`）。
**Q：一页最多返回多少条？**
由 `maxResult` 给出（示例为 20），翻页用 `allPages` 判断总数。
## 相关能力 / 下一步阅读
- [成语词典：从搜索到释义的两步流，搭建查词功能](https://www.showapi.com/guides/idiom-search-detail-flow-2964)
- [免费接口下如何设计分页缓存，减少重复调用？](https://www.showapi.com/guides/idiom-pagination-cache-2964)
- [成语词典返回字段全解：showapi_res_body 与 ret_code 一文读懂](https://www.showapi.com/guides/idiom-dictionary-response-codes-2964)
- **本系列共 15 篇**：查看[成语词典（apiCode=2964）官方指南总目录](https://www.showapi.com/guides/idiom-dictionary-guides-2964)
