儿童故事小程序如何集成童话故事集 API？从分类到详情的全链路设计
# 儿童故事小程序如何集成童话故事集 API？从分类到详情的全链路设计
> 元信息：童话故事集 API（apiCode=1700）· 全接入点 · 免费服务 · 适用人群：儿童 App / 小程序 / 绘本开发者 · 阅读时间约 9 分钟
## 核心要点
- 全链路三步走：1700-1 取分类菜单 → 1700-2 按 classifyId+keyword 拉列表 → 1700-3 用 id 取详情。
- 数据表应缓存 classifyId 映射、列表索引（id/title/classifyId）与详情正文，避免高频实时调用。
- 前端三级页面（分类 → 列表 → 详情）与三个接入点一一对应。
## Why：从一个想法到能上线的产品
假设你做一个"给孩子讲故事"的小程序：首页是分类书架，点进去是故事列表，再点进去是故事详情。这正好对应童话故事集 API 的三个接入点。本篇把这些串成一个可落地的设计与调用时序，让你不只是会调接口，而是能搭出一个完整产品。
## What：接口速览
| 页面 | 对应接入点 | 关键参数 | 返回 |
|------|-----------|----------|------|
| 分类书架 | 1700-1 | 无 | `storylist[]`（classify, classifyId） |
| 故事列表 | 1700-2 | classifyId + keyword + page | `contentlist[]` + 分页 |
| 故事详情 | 1700-3 | id | 单篇正文 |
## How：数据表与调用时序
### 1. 数据表设计（建议）
```sql
-- 分类表（来自 1700-1，变化慢，可全量缓存）
CREATE TABLE story_category (
classify_id VARCHAR(16) PRIMARY KEY,
classify_name VARCHAR(64)
);
-- 故事索引表（来自 1700-2，按分类+关键字缓存）
CREATE TABLE story_index (
story_id VARCHAR(32) PRIMARY KEY,
title VARCHAR(128),
classify_id VARCHAR(16),
keyword VARCHAR(64),
fetched_at DATETIME
);
-- 故事详情表（来自 1700-3，正文变化极慢）
CREATE TABLE story_detail (
story_id VARCHAR(32) PRIMARY KEY,
title VARCHAR(128),
classify VARCHAR(64),
content TEXT,
cached_at DATETIME
);
```
### 2. 调用时序（Python 示例骨架）
```python
import requests, time
APPKEY = "YOUR_APPKEY"
BASE = f"https://route.showapi.com/1700"
def api(point, data=None):
r = requests.post(f"{BASE}-{point}?appKey={APPKEY}", data=data or {},
headers={"content-type": "application/x-www-form-urlencoded"}, timeout=10)
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
raise SystemExit(body.get("remark"))
return body
# 步骤1：分类（缓存到 story_category）
cats = api(1)["storylist"]
# 步骤2：某分类下带关键字的列表（缓存到 story_index）
lst = api(2, {"classifyId": "2", "keyword": "小", "page": "1"})
story_ids = [it["id"] for it in lst["contentlist"]]
# 步骤3：用 id 取详情（缓存到 story_detail）
for sid in story_ids:
detail = api(3, {"id": sid})
print(detail["title"], len(detail["content"]))
time.sleep(0.2) # 控制频率，避免触档次限制
```
```javascript
const BASE = `https://route.showapi.com/1700`;
async function api(point, data) {
const r = await fetch(`${BASE}-${point}?appKey=YOUR_APPKEY`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams(data || {}),
});
const body = (await r.json()).showapi_res_body;
if (body.ret_code !== "0") throw new Error(body.remark);
return body;
}
const cats = await api(1);
const lst = await api(2, { classifyId: "2", keyword: "小", page: "1" });
for (const it of lst.contentlist) {
const d = await api(3, { id: it.id });
console.log(d.title, d.content.slice(0, 50));
}
```
### 3. 前端三级页面
- **分类页**：渲染 `story_category`，点某项带 `classifyId` 跳列表页。
- **列表页**：调用 1700-2 渲染 `contentlist`（标题+分类），点某项带 `id` 跳详情页。
- **详情页**：调用 1700-3 渲染 `title` + `content`，正文做换行与转义处理。
## 返回示例与解析
链路数据流向：`storylist[].classifyId` → `contentlist[].id` → `detail.content`。详情见各接入点单独指南：
- [故事分类接入点](https://www.showapi.com/guides/child-story-classify-guide-1700)
- [故事列表实战](https://www.showapi.com/guides/child-story-list-guide-1700)
- [故事详情接入点](https://www.showapi.com/guides/child-story-detail-guide-1700)
## 进阶 / 边界
- **keyword 必填**：1700-2 的 `keyword` 必填，列表页若想"按分类浏览全部"，需先确定可接受的关键字策略（文档未给空值约定，勿臆造）。
- **控制调用频率**：免费服务有档次限制，批量建库时加 `sleep`、用分页 `allPages` 控制上限（见[缓存与分页策略](https://www.showapi.com/guides/child-story-cache-1700)）。
- **内容缓存**：分类与详情正文几乎不变，强烈建议落库缓存，仅列表按分类+关键字做短时效缓存。
## FAQ
**Q: 三个接入点能一次拿到全部故事吗？**
A: 不能。没有批量接入点，必须"分类→列表→详情"逐级调用；详情需逐篇用 id 取。
**Q: 小程序前端能直连 route.showapi.com 吗？**
A: 不建议在前端暴露 AppKey。应走自己的后端代理，由服务端持有 AppKey 并做缓存与限流。
**Q: 列表页没有正文，能做搜索预览吗？**
A: 列表只返回标题与分类，预览摘要需额外调 1700-3 取 `content` 前若干字，注意频率。
**Q: 分类很多、故事很多，第一次建库要调多少次？**
A: 约等于 分类数×关键字数×页数×每篇详情，量级不小；务必分页+限流+缓存，否则易触发档次限制。
## 相关能力 / 下一步阅读
- [童话故事集 API：故事列表搜索与分页实战](https://www.showapi.com/guides/child-story-list-guide-1700)
- [免费接口也别乱调用：内容缓存与分页拉取策略](https://www.showapi.com/guides/child-story-cache-1700)
- [童话故事集 API 免费档位说明](https://www.showapi.com/guides/child-story-free-tier-1700)
- **本系列共 12 篇**：查看[童话故事集 API 指南总目录](https://www.showapi.com/guides/child-story-guides-1700)
