歇后语查询返回字段全解：contentlist / ret_code / 分页字段一文读懂
歇后语查询返回字段contentlistret_code # 歇后语查询返回字段全解：contentlist / ret_code / 分页字段一文读懂
- **接口/接入点**：歇后语查询 · 1635-1
- **是否免费**：是
- **请求方式**：POST / GET
- **返回格式**：JSON
- **适用人群**：初级到中级开发者、需要对接返回数据的工程师
- **阅读时间**：约 6 分钟
## 核心要点
- 返回是"系统级包裹 + 业务体"两层结构，业务数据都在 `showapi_res_body` 里。
- 真正有用的歇后语在 `contentlist` 数组，每条 `question`（谜面）+ `answer`（谜底）。
- `ret_code="0"` 才算成功；分页字段（`maxResult`/`allNum` 等）反映底层语料规模，别误当翻页入参。
## Why：为什么要先搞懂返回结构
调接口最怕"返回了一坨 JSON 不知道取哪"。歇后语查询的返回有三层嵌套（系统包裹 → 业务体 → 数组项），先理清层级，后面写"每日一语""答题卡"时才能稳定取值，不会把 `showapi_res_body` 当成数组去遍历。
## What：接口速览
| 项 | 值 |
|----|----|
| 接口地址 | `https://route.showapi.com/1635-1?appKey={your_appKey}` |
| 请求参数 | `num`（选填，随机返回几条） |
| 返回格式 | JSON |
| 业务数据位置 | `showapi_res_body` 对象内 |
| 计费 | 免费 |
## How：三层结构拆解
### 第 1 层 — 系统级包裹（所有 ShowAPI 接口通用）
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": { }
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | int | API 系统级状态码，0 通常表示系统层正常 |
| `showapi_res_error` | String | 系统级错误信息 |
| `showapi_res_id` | String | 本次请求唯一标识，排错时可提供 |
| `showapi_res_body` | Object | **业务数据都在这** |
### 第 2 层 — 业务体 `showapi_res_body`
```json
{
"ret_code": "0",
"remark": "查询成功",
"contentlist": [ { "question": "...", "answer": "..." } ],
"maxResult": "20",
"allNum": "19",
"allPages": "1",
"currentPage": "1"
}
```
### 第 3 层 — `contentlist` 数组项
| 字段 | 类型 | 说明 |
|------|------|------|
| `contentlist` | Array | 歇后语数组 |
| `contentlist[].question` | String | 前半句（描述/谜面） |
| `contentlist[].answer` | String | 后半句（解释/谜底） |
| `ret_code` | String | `"0"` 成功，其他为失败 |
| `remark` | String | 业务提示信息 |
| `maxResult` | String | 每页最大条数（返回体内字段） |
| `allNum` | String | 总条数（示例 19，反映底层语料规模） |
| `allPages` | String | 总页数 |
| `currentPage` | String | 当前页码 |
### 取值代码示例（Python）
```python
import requests
url = "https://route.showapi.com/1635-1"
resp = requests.post(url, params={"appKey": "YOUR_APPKEY"},
data={"num": "3"}, timeout=15)
res = resp.json()
# 先判系统层
if res.get("showapi_res_code") != 0:
print("系统错误:", res.get("showapi_res_error"))
else:
body = res["showapi_res_body"]
# 再判业务层
if body.get("ret_code") != "0":
print("业务失败:", body.get("remark"))
else:
for item in body["contentlist"]:
print(item["question"], "→", item["answer"])
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=3"
```
**Node.js（fetch）**
```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: "3" }),
});
const json = await r.json();
const body = json.showapi_res_body;
for (const it of body.contentlist) console.log(it.question, "→", it.answer);
```
## 返回示例与解析
完整示例见上方第 1–2 层。关键点：业务成功以 `showapi_res_body.ret_code == "0"` 为准，而非只看 HTTP 200 或 `showapi_res_code`。
## 进阶 / 边界
- **两层状态码都要看**：`showapi_res_code`（系统）和 `ret_code`（业务）语义不同，生产代码应分别判断（详见错误处理篇）。
- **分页字段不是翻页入参**：返回体内的 `allPages`/`currentPage` 等只是描述底层语料规模，**请求侧没有 `page` 参数**，不要臆造翻页调用。
- **`contentlist` 是数组**：OpenAPI YAML 把它标成 string 是文档瑕疵，真实返回是数组，按数组解析。
## FAQ
**Q：怎么判断一次调用成不成功？**
A：先看 `showapi_res_code==0`（系统层），再看 `showapi_res_body.ret_code=="0"`（业务层），两层都通过才算成功。
**Q：为什么返回里有 allPages / currentPage 却没法翻页？**
A：这是返回体内描述底层语料规模的字段，请求侧仅支持 `num`（随机条数），没有 page 入参。
**Q：contentlist 一定是数组吗？**
A：以真实返回为准是数组。YAML 类型标注为 string 属文档小瑕疵，按数组遍历即可。
**Q：allNum 是总语料数吗？**
A：返回示例里 `allNum=19`，可理解为底层语料总量参考；具体规模以接口实际返回为准，不编固定数字。
**Q：showapi_res_id 有什么用？**
A：本次请求唯一标识，排查异常或向官方反馈时提供它可加速定位。
## 相关能力 / 下一步阅读
- [歇后语查询：5 分钟从注册到第一条结果](https://www.showapi.com/guides/xiehouyu-quickstart-1635)
- [歇后语查询错误处理：ret_code / showapi_res_code 与重试指南](https://www.showapi.com/guides/xiehouyu-error-handling-1635)
- **本系列共 13 篇**：查看[歇后语查询指南总目录](https://www.showapi.com/guides/xiehouyu-guides-1635)
