健康知识 API 分页与总量处理：pagebean 的 allPages / allNum / maxResult
# 健康知识 API 分页与总量处理：pagebean 的 allPages / allNum / maxResult
- **接口/接入点**：健康知识 · 搜索知识 `90-87`（免费）
- **请求方式**：POST / GET ｜ **返回格式**：JSON
- **适用人群**：全栈开发者 ｜ **阅读时间**：约 7 分钟
## 核心要点
- 搜索结果用 `pagebean` 承载分页：`allNum`（总条数）、`allPages`（总页数）、`currentPage`（当前页）、`maxResult`（每页最大数）。
- 每页最大返回 20 条；`page` 从 1 开始递增翻页，到 `allPages` 即末页。
- 用 `allPages` 控制翻页上限，避免无效请求；用 `allNum` 做"共 N 条"展示。
## Why：分页决定体验与成本
健康知识搜索可能返回几十条甚至更多结果。如果不处理分页，要么一次只看到第一页，要么反复请求越界页浪费免费额度。理解 `pagebean` 四个字段，就能做出正确的"上一页/下一页"、无限滚动和"共 N 条"提示，既提升体验又省调用。
## What：pagebean 字段含义
| 字段 | 类型 | 含义 |
|------|------|------|
| `allPages` | number | 总页数 |
| `currentPage` | number | 当前页码 |
| `allNum` | number | 总条数 |
| `maxResult` | number | 每页最大数（文档明确每页最大 20 条） |
| `contentlist` | array | 当前页数据 |
## How：基于 pagebean 的分页器
**翻页循环（Python）**
```python
import requests
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/90-87"
collected = []
page = 1
while True:
resp = requests.post(
URL,
params={"appKey": APP_KEY},
data={"key": "养生", "tid": "", "page": str(page)},
timeout=15,
).json()
body = resp["showapi_res_body"]
if body.get("ret_code") != "0":
break
pb = body["pagebean"]
collected.extend(pb["contentlist"])
if page >= pb["allPages"]: # 到达末页
break
page += 1
print(f"共拉取 {len(collected)} 条，总条数 {pb['allNum']}，总页数 {pb['allPages']}")
```
**前端分页器（示意）**
```javascript
function buildPager(pb) {
// pb: { allPages, currentPage, allNum, maxResult }
return {
total: pb.allNum,
pageCount: pb.allPages,
pageSize: pb.maxResult, // 每页最大 20
current: pb.currentPage,
hasNext: pb.currentPage < pb.allPages,
};
}
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": "0",
"pagebean": {
"allPages": 3,
"currentPage": 1,
"allNum": 45,
"maxResult": 20,
"contentlist": [ { "id": "100001", "title": "感冒了怎么办" } ]
}
}
}
```
含义：总共 45 条、3 页、每页最多 20 条，当前第 1 页。第 2 页 `page=2` 取第 21~40 条，第 3 页取剩余 5 条。
## 进阶 / 边界
- **不要越过 allPages**：`page` 超过 `allPages` 会得到空 `contentlist`，属于无效调用，既浪费额度也无意义。
- **每页上限固定 20**：`maxResult` 体现每页最大数，客户端无法请求更大的页宽；做"加载更多"时按 20 条一页分批。
- **总数用于展示**：`allNum` 适合在列表顶部展示"共 N 条结果"，但不要把它当作可预测的每页条数（末页通常不足 20）。
## FAQ
**Q：每页到底多少条？**
A：文档明确每页最大返回 20 条，由 `maxResult` 字段体现；末页可能少于 20 条。
**Q：page 从 0 还是 1 开始？**
A：文档示例中 `page` 以字符串形式传参（如 "1"），按 1 起始理解；具体边界以接口实际返回为准。
**Q：allPages 和 allNum 不一致怎么办？**
A：正常。`allNum` 是总条数，`allPages = ceil(allNum / maxResult)`；两者是同一总量的不同表达。
**Q：可以一次拉全部页吗？**
A：可以循环翻页直到 `allPages`，但注意免费档位限制，必要时做缓存或按需加载（见[免费额度策略](https://www.showapi.com/guides/health-knowledge-free-quota-90)）。
## 相关能力与下一步阅读
- [健康知识 API：搜索知识接入实战（关键词 / 分类 / 分页）](https://www.showapi.com/guides/health-knowledge-search-90)
- [健康知识 API：免费额度与档位限制下的合理调用策略](https://www.showapi.com/guides/health-knowledge-free-quota-90)
- [健康知识 API 返回字段全解：分类列表 / 搜索结果 / 知识详情三大结构](https://www.showapi.com/guides/health-knowledge-fields-90)
- **本系列共 12 篇**：查看[健康知识 API 使用指南总目录](https://www.showapi.com/guides/health-knowledge-guides-90)
