童话故事集 API 返回字段全解：storylist / contentlist / 分页字段一文读懂

# 童话故事集 API 返回字段全解：storylist / contentlist / 分页字段一文读懂 > 元信息：童话故事集 API（apiCode=1700）· 免费服务 · 返回 JSON · 适用人群：已接入或准备接入的开发者 · 阅读时间约 7 分钟 ## 核心要点 - 所有业务数据都包在系统级 `showapi_res_body` 内；判断成功看 `showapi_res_body.ret_code == "0"`。 - 三接入点返回数组命名不一致：1700-1 用 `storylist[]`，1700-2 用 `contentlist[]`，写代码别混用。 - 分页字段只在 1700-2 出现：`allNum / allPages / currentPage / maxResult`。 ## Why：为什么值得专门搞懂返回结构 接口返回是嵌套 JSON，系统级字段和业务字段混在一起。如果一开始没看清结构，很容易把 `showapi_res_body` 当成业务根、或把 1700-1 的 `storylist` 当成 1700-2 的 `contentlist`，导致取值报错。本篇把三层结构、各接入点字段、以及命名差异一次讲清。 ## What：接口速览 | 项目 | 说明 | |------|------| | 系统级封装 | 响应最外层为 `showapi_res_code / showapi_res_error / showapi_res_id`，业务数据在 `showapi_res_body` | | 成功判断 | `showapi_res_body.ret_code == "0"` 为成功，其他为失败 | | 接入点 | 1700-1 分类、1700-2 列表（含分页）、1700-3 详情 | ## How：三层结构拆解 ### 第一层：系统级 ```json { "showapi_res_code": 0, "showapi_res_error": "", "showapi_res_id": "ce135f6739294c63be0c021b76b6fbff", "showapi_res_body": { } } ``` - `showapi_res_code`：系统级状态码，0 成功。 - `showapi_res_error`：系统级错误信息，成功时为空串。 - `showapi_res_id`：本次请求标识。 - `showapi_res_body`：业务数据容器，下面所有字段都在它里面。 ### 第二层：业务状态字段（三接入点共有） | 字段 | 类型 | 说明 | |------|------|------| | `ret_code` | String | 业务状态码，"0" 成功，其他失败 | | `remark` | String | 提示信息，如「查询成功！」 | ### 第三层：各接入点业务数组 **1700-1 故事分类**：返回 `storylist[]` | 字段 | 类型 | 说明 | |------|------|------| | `classify` | String | 分类名称，如「安徒生童话」 | | `classifyId` | String | 分类 Id，用于 1700-2 的 `classifyId` 参数 | **1700-2 故事列表**：返回 `contentlist[]` 及分页字段 | 字段 | 类型 | 说明 | |------|------|------| | `contentlist[].title` | String | 故事名 | | `contentlist[].classifyId` | String | 分类 Id | | `contentlist[].id` | String | 故事 id，用于 1700-3 | | `allNum` | String | 符合条件的总数 | | `allPages` | String | 总页数 | | `currentPage` | String | 当前页 | | `maxResult` | String | 单页最大返回条数（默认 20） | **1700-3 故事详情**：返回单条故事对象 | 字段 | 类型 | 说明 | |------|------|------| | `id` | String | 故事 id | | `title` | String | 故事名称 | | `classify` | String | 分类名称 | | `classifyId` | String | 分类 id | | `content` | String | 故事正文 | ## 返回示例与解析 ```json { "showapi_res_body": { "ret_code": "0", "remark": "查询成功！", "allPages": 1, "contentlist": [ { "id": "5ba1c830c1b4f34642f5e66a", "title": "谜语童话", "classifyId": "3" }, { "id": "5ba1c5dbc1b4be0a124a844c", "title": "老橡树的最后一梦(圣诞童话)", "classifyId": "2" } ], "currentPage": 1, "allNum": 15, "maxResult": 20 } } ``` > 注意：1700-1 的文档「返回体」字段表写的是扁平 `classify/classifyId`，但真实返回示例是 `storylist[]` 数组。以真实返回结构（数组）为准。 ## 进阶 / 边界 - **命名差异是真实存在**：`storylist`（1700-1）与 `contentlist`（1700-2）是不同字段名，不要以为统一叫 `list`。做通用解析器时建议按接入点分别映射。 - **失败枚举未公开**：文档只给出 `ret_code="0"` 成功，未列出具体失败码。遇到非 0 时以 `remark` 实际文案为准，不要自己枚举。 - **`content` 是长文本**：1700-3 的 `content` 可能较长，前端展示注意截断、换行与 XSS 转义。 ## FAQ **Q: 为什么 1700-1 和 1700-2 的数组名字不一样？** A: 这是官方文档/接口的真实字段命名，1700-1 用 `storylist`、1700-2 用 `contentlist`，按各自字段取值即可，属于已知差异而非 Bug。 **Q: ret_code 非 0 时怎么拿错误信息？** A: 读 `showapi_res_body.remark`，里面是本次的提示文案；同时可参考系统级 `showapi_res_error`。 **Q: maxResult 能改吗？** A: 文档未提供自定义每页条数的参数，默认 20。需要更多数据就靠 `page` 翻页，直到 `currentPage == allPages`。 **Q: 分类下的故事总数怎么拿？** A: 调 1700-2 后读 `allNum`（总数）与 `allPages`（总页数），据此决定翻几页。 ## 相关能力 / 下一步阅读 - [童话故事集 API：5 分钟接入](https://www.showapi.com/guides/child-story-quickstart-1700) - [童话故事集 API：故事列表搜索与分页实战](https://www.showapi.com/guides/child-story-list-guide-1700) - [童话故事集 API：故事详情接入点怎么用](https://www.showapi.com/guides/child-story-detail-guide-1700) - **本系列共 12 篇**：查看[童话故事集 API 指南总目录](https://www.showapi.com/guides/child-story-guides-1700)