周公解梦 API 返回字段全解：ret_code、contentlist、分页字段一文读懂
周公解梦返回字段ret_codecontentlist分页字段 # 周公解梦 API 返回字段全解：ret_code、contentlist、分页字段一文读懂
> 接口：免费解梦详细（apiCode 1601）· 接入点：解梦详细（1601-2）· **免费** · 返回 JSON · 适用人群：中高级开发者、需要稳定解析返回结构的工程师 · 阅读约 7 分钟
## 核心要点
- 返回分两层：系统级 `showapi_res_code` 与业务级 `showapi_res_body.ret_code`，两者都要判。
- `contentlist` **真实类型是对象数组**（每个元素含 `name` 与 `detailList`），文档文字标注为 "String" 与实际不符，以实际返回为准。
- 分页四字段 `maxResult`/`allNum`/`allPages`/`currentPage` 都在 `showapi_res_body` 内，用于控制翻页。
## Why：为什么要把返回结构吃透
解析接口最怕两件事：一是只判了系统码没判业务码，导致失败请求被当成成功；二是把 `contentlist` 当字符串处理，结果取不到 `name`/`detailList`。本文把返回结构的每一层讲清楚，照着写就不会踩坑。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/1601-2?appKey={your_appKey}` |
| 请求方式 | POST / GET |
| 返回格式 | JSON |
| 业务数据容器 | `showapi_res_body`（系统封装，业务字段都在里面） |
| 接入点说明 | 内容参考《周公解梦全书》部分信息，提供解读参考（文化参考，非科学/医疗结论） |
## How：逐层解析
一次完整返回的最外层结构：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": { }
}
```
**1）系统级字段（最外层）**
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | Number | 系统级状态码，`0` 为成功 |
| `showapi_res_error` | String | 系统级错误信息，成功时为空 |
| `showapi_res_id` | String | 本次请求标识 |
| `showapi_res_body` | Object | 业务数据容器，下文所有字段都在这里 |
**2）业务级字段（`showapi_res_body` 内）**
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | String | 业务状态码，`"0"` 为成功，其余为失败（文档未枚举具体非零值） |
| `contentlist` | **Array** | 结果集合，每个元素是 `{ name, detailList }` |
| `maxResult` | String | 每页最大结果数 |
| `allNum` | String | 总结果数 |
| `allPages` | String | 总页数 |
| `currentPage` | String | 当前页 |
**3）`contentlist` 元素结构（关键）**
```json
{
"name": "疯子",
"detailList": [
"疯子活在自己的世界里……是一种好运。",
"梦见疯子通常预示你将有好运气。"
]
}
```
- `name`：梦境名（String）。
- `detailList`：解读文本数组（Array of String），可能含原版周公解梦、案例分析、心理学解梦等段落。
**判错与取值的健壮写法（Python）**
```python
import requests
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/1601-2"
resp = requests.post(
URL, params={"appKey": APP_KEY},
data={"keyWords": "飞", "page": "1"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
data = resp.json()
# 第一层：系统级
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误: {data.get('showapi_res_error')}")
body = data.get("showapi_res_body", {})
# 第二层：业务级
if body.get("ret_code") != "0":
raise RuntimeError(f"业务失败: ret_code={body.get('ret_code')}")
# 第三层：结果数组（注意是数组，不是字符串）
results = body.get("contentlist") or []
for item in results:
print(item.get("name"), "->", len(item.get("detailList", [])), "条解读")
```
## 返回示例与解析
见《[5 分钟接入](https://www.showapi.com/guides/dream-quickstart-1601)》中的完整示例：关键词「飞」返回 `allNum=2`、`allPages=1`、`maxResult=10`，`contentlist` 含「疯子」「疯子追杀我」两条，每条带若干 `detailList` 文本。
## 进阶 / 边界
- **文档标注偏差提醒**：官方文档把 `contentlist` 写成 `String`，但真实返回是对象数组。所有解析代码都要按**数组**处理，不要当字符串 `split`。
- **两层码都要判**：只判 `showapi_res_code` 不判 `ret_code`，可能在业务失败时误判成功。
- **`ret_code` 无具体枚举**：文档仅约定「0 成功，其余失败」，没有像 -2/-3 这样的细错误码，失败时统一按失败处理并读取 `showapi_res_error`。
- **内容为文化参考**：`detailList` 文本来自《周公解梦全书》类资料，属文化参考，前端展示时应加上「仅供娱乐/参考」提示，不要包装成科学或医疗结论。
## FAQ
**Q1：为什么我的代码取不到 name / detailList？**
多半是把 `contentlist` 当字符串处理了。它是数组，先遍历数组再取每个元素的 `name` 与 `detailList`。
**Q2：`showapi_res_code` 和 `ret_code` 有什么区别？**
前者是系统级（请求是否成功到达并处理），后者是业务级（查询本身是否成功）。两个都要判。
**Q3：`ret_code` 返回非 0 时有没有错误码对照表？**
文档未提供具体非零值的枚举，只约定「0 成功，其余失败」。失败时读 `showapi_res_error` 排查。
**Q4：`detailList` 里为什么有「心理学解梦」「原版周公解梦」等混杂内容？**
这是接口本身返回的内容形态（同一梦境的多角度解读），由你决定前端展示时是否分段、折叠或筛选。
**Q5：分页字段是数字还是字符串？**
示例中为字符串（如 `"allNum":"2"`），解析时建议先按字符串读取或做类型兼容，避免强转报错。
## 相关能力 / 下一步阅读
- [周公解梦 API：5 分钟接入，从注册到查出第一个梦境解读](https://www.showapi.com/guides/dream-quickstart-1601)
- [周公解梦 API：关键词怎么查才准？关键词选取与结果解读实战](https://www.showapi.com/guides/dream-keywords-guide-1601)
- [周公解梦 API：分页与结果集怎么用？maxResult/allNum/allPages 详解](https://www.showapi.com/guides/dream-pagination-1601)
- **本系列共 8 篇**：查看[周公解梦 API 指南总目录](https://www.showapi.com/guides/dream-guides-1601)
