歇后语查询 num 参数详解：随机条数、maxResult 与返回上限
# 歇后语查询 num 参数详解：随机条数、maxResult 与返回上限
- **接口/接入点**：歇后语查询 · 1635-1
- **是否免费**：是
- **请求方式**：POST / GET
- **返回格式**：JSON
- **适用人群**：中高级开发者、需要精确控制返回量的工程师
- **阅读时间**：约 6 分钟
## 核心要点
- 请求侧**唯一参数**是 `num`（选填，String）：随机返回几条，示例值 `3`。
- 返回体内的 `maxResult`/`allNum`/`allPages`/`currentPage` 是描述底层语料规模的字段，**不是翻页入参**。
- 底层语料有限（示例 `allNum=19`），随机可能重复；量大场景靠本地去重。
## Why：为什么要把 num 讲清楚
很多开发者看到返回里有 `allPages`/`currentPage`，误以为能翻页；看到 `num` 又不确定传不传。本文把"请求有什么、返回有什么"一次讲清，避免误用。
## What：参数与字段对照
| 位置 | 名称 | 类型 | 说明 |
|------|------|------|------|
| 请求 | `num` | String（选填） | 随机返回几条，如 `3`；不传由接口给默认值 |
| 返回 | `maxResult` | String | 每页最大条数（返回体内字段） |
| 返回 | `allNum` | String | 总条数（示例 19，反映底层语料规模） |
| 返回 | `allPages` | String | 总页数 |
| 返回 | `currentPage` | String | 当前页码 |
> **重要**：请求侧只有 `num`，**没有 `page` / `pageSize` 等翻页参数**（已与 OpenAPI YAML 核实 `parameters: []` 仅 `num`）。
## How：用法示例
### 取 5 条
```python
import requests
r = requests.post("https://route.showapi.com/1635-1",
params={"appKey": "YOUR_APPKEY"},
data={"num": "5"}, timeout=15)
body = r.json()["showapi_res_body"]
print("本次返回条数:", len(body["contentlist"]))
print("底层语料总量 allNum:", body.get("allNum"))
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1635-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" -d "num=5"
```
**Node.js**
```javascript
const r = await fetch("https://route.showapi.com/1635-1?appKey=YOUR_APPKEY", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ num: "5" }),
});
const body = (await r.json()).showapi_res_body;
console.log("返回条数:", body.contentlist.length, "allNum:", body.allNum);
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": "0",
"contentlist": [ { "question": "刘阿斗的江山", "answer": "白送" } ],
"maxResult": "20",
"allNum": "19",
"allPages": "1",
"currentPage": "1"
}
}
```
`allNum=19` 说明底层语料约 19 条；`maxResult=20` 表示单页最大条数（返回体内描述字段）。
## 进阶 / 边界
- **`num` 不传会怎样**：接口会按自身默认返回，建议始终显式传以稳定结果。
- **`num` 上限**：以接口实际返回为准，文档未给固定上限；不要臆造"最大 100"之类数字。
- **重复问题**：语料有限 + 随机，多次调用易重复，生产用本地去重（见缓存去重篇）。
## FAQ
**Q：num 不传行吗？**
A：可以，接口会给默认条数；但为结果稳定建议显式传。
**Q：能翻页吗？**
A：不能，请求侧只有 `num`，返回里的 allPages/currentPage 只是描述语料规模，无 page 入参。
**Q：num 最大能传多少？**
A：以接口实际返回为准，文档未给固定上限，不编数字。
**Q：为什么 allNum 才 19？**
A：示例值反映底层语料规模有限；实际规模以接口返回为准，不要当固定常量。
**Q：maxResult 和 num 什么关系？**
A：`maxResult` 是返回体内"每页最大条数"描述字段，`num` 是你请求的随机条数，二者不在同一层，不要混淆。
## 相关能力 / 下一步阅读
- [免费接口也要稳：歇后语查询本地缓存与去重策略](https://www.showapi.com/guides/xiehouyu-cache-dedup-1635)
- [歇后语查询返回字段全解：contentlist / ret_code / 分页字段一文读懂](https://www.showapi.com/guides/xiehouyu-response-fields-1635)
- **本系列共 13 篇**：查看[歇后语查询指南总目录](https://www.showapi.com/guides/xiehouyu-guides-1635)
