免费名言警句：返回字段全解（contentlist / ret_code / allNum）
免费名言警句返回字段ret_codecontentlist # 免费名言警句：返回字段全解（contentlist / ret_code / allNum）
> 接口 1839-1 · 免费 · 返回 JSON · 适用人群：已接入或准备接入的开发者 · 阅读时间：约 4 分钟
## 核心要点
- ShowAPI 统一用 `showapi_res_body` 包裹业务数据；名言内容在 `contentlist` 数组里。
- 成功与否看 `ret_code`（业务层）与 `showapi_res_code`（系统层），二者都要判断。
- `allNum` / `allPages` / `maxResult` / `currentPage` 描述分页与条数，`content` 是"名言+作者"合并字符串。
## Why
很多接入报错不是接口坏了，而是没分清"系统级包裹"和"业务数据"。比如只看顶层 `showapi_res_code` 为 0，就以为拿到名言了，结果 `contentlist` 是空的——其实业务层 `ret_code` 才是关键。本文把每一层字段讲清楚，让你拿到返回就知道怎么判错、怎么取数。
## What
**接口速览**
| 项 | 值 |
|----|----|
| 请求地址 | `https://route.showapi.com/1839-1?appKey=YOUR_APPKEY` |
| 返回格式 | JSON |
| 业务数据位置 | `showapi_res_body` 对象内 |
| 成功标志 | 系统层 `showapi_res_code == 0` 且 业务层 `ret_code == "0"` |
## How
### 步骤 1：识别两层结构
顶层是 ShowAPI 统一信封，包含 `showapi_res_code` / `showapi_res_error` / `showapi_res_id` / `showapi_res_body`。真正的内容在 `showapi_res_body`。
### 步骤 2：先判系统层，再判业务层
```python
import requests
r = requests.get(
"https://route.showapi.com/1839-1",
params={"appKey": "YOUR_APPKEY", "num": "3"},
timeout=15,
)
data = r.json()
# 1) 系统层
if data.get("showapi_res_code") != 0:
print("系统级错误：", data.get("showapi_res_error"))
else:
body = data["showapi_res_body"]
# 2) 业务层
if body.get("ret_code") != "0":
print("业务错误：", body.get("remark"))
else:
for it in body["contentlist"]:
print(it["content"])
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"allNum": 3,
"allPages": 1,
"contentlist": [
{ "content": "德盛者威广，力盛者骄众。齐桓公尚德以霸，秦二世尚刑而亡。——陆贾" }
],
"currentPage": 1,
"maxResult": 3,
"remark": "查询成功！",
"ret_code": "0"
}
}
```
### 系统级字段（统一信封）
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | Integer | 系统级状态码，0 表示请求被正常处理 |
| `showapi_res_error` | String | 系统级错误信息 |
| `showapi_res_id` | String | 本次请求的唯一标识 |
| `showapi_fee_num` | Integer | 本次调用计费次数（系统级，文档标注于 envelope） |
### 业务字段（`showapi_res_body` 内）
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | String | `"0"` 成功，其他为失败 |
| `remark` | String | 提示信息，如"查询成功！" |
| `maxResult` | String | 当前页最大值（等于请求传入的 `num`） |
| `currentPage` | String | 当前页码（默认 1） |
| `contentlist` | Object[] | 内容列表 |
| `contentlist[].content` | String | 名言 + 作者（合并字符串，如"王安石（宋）"） |
| `allPages` | String | 页码数 |
| `allNum` | String | 内容条数 |
## 进阶 / 边界
- 本接口为单页随机返回，没有真正的多页数据集，`allPages` / `currentPage` 实质恒为 1，**不要**据此做翻页逻辑。
- `content` 把名言和作者拼在一起，作者常以"——""--"或"（朝代）"后缀形式出现，需自行正则拆分才能独立展示作者。
- `ret_code` 是字符串 `"0"`，比较时别写成整数 `0`。
## FAQ
**Q1：`showapi_res_code` 和 `ret_code` 有什么区别？**
A：前者是系统级（请求是否被正确接收处理），后者是业务级（名言是否成功取回）。二者都正常才算真正成功。
**Q2：`contentlist` 为空但 `ret_code` 是 0，正常吗？**
A：接口设计上 `ret_code=0` 时通常会有内容；若偶发为空，先确认是否触发了免费档位限制，再核对 `remark` 提示。
**Q3：`allPages` 能翻页吗？**
A：本接口是随机返回，不是可翻页的数据集，`allPages` 恒为 1，不支持 offset/page 翻页。
**Q4：`ret_code` 非 0 时有哪些取值？**
A：文档只明确 `"0"` 为成功、其他为失败，未给出完整失败码枚举；排查时以 `remark` 文案为准。
## 相关能力 / 下一步阅读
- [免费名言警句：5 分钟接入，从注册到第一条名言](https://www.showapi.com/guides/famous-quotes-quickstart-1839)
- [免费名言警句：num 参数怎么用？最多 10 条与"随机返回"机制](https://www.showapi.com/guides/famous-quotes-num-param-1839)
- [免费名言警句：常见问题与排查（ret_code 非 0 / 返回为空 / 免费档位限制）](https://www.showapi.com/guides/famous-quotes-faq-1839)
- **本系列共 10 篇**：查看[免费名言警句指南总目录](https://www.showapi.com/guides/famous-quotes-guides-1839)
