笑话大全返回字段全解：showapi_res_body 与 id/title/text 一文读懂
# 笑话大全返回字段全解：showapi_res_body 与 id/title/text 一文读懂
> 接口 341-5 · 免费 · JSON · 适用人群：已接入或准备接入的开发者 · 阅读时间：约 4 分钟
## 核心要点
- 返回分两层：系统级包裹（`showapi_res_*`）+ 业务体 `showapi_res_body`。
- 笑话本身只有 6 个业务字段：`id` / `title` / `text` / `ret_code` / `remark` / `ct`。
- `ret_code = 0` 才是成功；系统级 `showapi_res_code` 与业务级 `ret_code` 是两个不同层级的状态。
## Why
接入任何接口，第一件事是搞清楚"返回的字段哪个能用、哪个只是系统元数据"。笑话大全的返回被 ShowAPI 统一包裹了一层系统字段，新手容易把 `showapi_res_code` 和 `showapi_res_body.ret_code` 搞混，或误把 `title` 当唯一标题。本篇用一张表把所有字段讲清楚，让你写解析代码时不再猜。
## What
| 项 | 说明 |
|----|------|
| 返回结构 | 系统级对象 + `showapi_res_body`（业务体） |
| 业务字段数 | 6 个（`id` `title` `text` `ret_code` `remark` `ct`） |
| 成功判定 | `showapi_res_body.ret_code == 0` |
| 数据来源 | 字段结构与 OpenAPI 3.0 文档一致 |
## How
解析时先取 `showapi_res_body`，再读里面的业务字段；不要把系统级字段当笑话内容。
```python
import requests
APP_KEY = "YOUR_APPKEY"
data = requests.post(
"https://route.showapi.com/341-5",
params={"appKey": APP_KEY},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=20,
).json()
body = data["showapi_res_body"]
print("系统级状态码 showapi_res_code =", data.get("showapi_res_code"))
print("业务成功? ret_code =", body.get("ret_code")) # 0 为成功
print("笑话正文 text =", body.get("text"))
```
## 返回示例与解析
```json
{
"showapi_res_error": "",
"showapi_fee_num": 1,
"showapi_res_code": 0,
"showapi_res_id": "69aa6d3cfb638c5c252249e7",
"showapi_res_body": {
"id": "69a921a1530719e3c602fe0b",
"title": "讽刺、荒唐的爆笑事儿",
"text": "博士毕业两年多，父母从老家来看我……",
"ret_code": 0,
"remark": "查询成功！",
"ct": "2026-03-05 14:24:33.420"
}
}
```
### 系统级字段（包裹层）
| 字段 | 类型 | 含义 |
|------|------|------|
| `showapi_res_code` | 整数 | API 网关整体状态码，0 一般表示网关正常 |
| `showapi_res_error` | 字符串 | 网关错误信息，成功时为空 |
| `showapi_res_id` | 字符串 | 本次请求唯一标识，工单排查用 |
| `showapi_fee_num` | 整数 | 本次调用的计费次数（免费接口也返回，通常为 1） |
### 业务字段（`showapi_res_body` 内）
| 字段 | 类型 | 含义 | 展示建议 |
|------|------|------|---------|
| `id` | String | 本条笑话唯一 id | 可做去重 key |
| `title` | String | 分类标题（文档标注"会重复"） | 可不展示，或仅作分类标签 |
| `text` | String | 笑话正文 | **主要展示内容** |
| `ret_code` | Number | `0`=成功，其他=失败 | 先判它再取 `text` |
| `remark` | String | 返回描述，如"查询成功！" | 失败时可展示给用户 |
| `ct` | String | 返回时间（如 `2026-03-05 14:24:33.420`） | 一般无需展示 |
## 进阶 / 边界
- **两个"成功"要分清**：`showapi_res_code` 是网关层；真正的业务成败看 `showapi_res_body.ret_code`。建议以 `ret_code` 为准。
- **`title` 会重复**：文档明确说明，别把它当唯一标题或主键。
- **没有错误码枚举**：本接口文档/OpenAPI 未给出 `ret_code` 的非零枚举值，遇到非 0 时读 `remark` 描述即可，不要臆造错误码含义（排查见[调用失败排查](https://www.showapi.com/guides/joke-api-error-341)）。
## FAQ
**Q1：showapi_res_code 和 ret_code 有什么区别？**
前者是 ShowAPI 网关的状态码（请求是否送达/鉴权是否通过），后者是业务体里的执行结果。`ret_code = 0` 才是"拿到笑话成功"，应以它为准。
**Q2：text 为空或不存在怎么办？**
先确认 `ret_code == 0`；若非 0，读 `remark` 看原因。正常成功时 `text` 必有内容。
**Q3：title 每次都一样，是不是出错了？**
不是。文档明确标注 `title`"会重复"，是分类标题，非唯一标识，属正常现象。
**Q4：showapi_fee_num 是什么意思？免费接口为什么有计费次数？**
它是 ShowAPI 统一的调用计费次数统计字段，免费接口也会返回（通常为 1），不代表已扣费。
**Q5：ct 时间是什么时区？**
返回示例形如 `2026-03-05 14:24:33.420`，为接口服务端时间字符串，展示时一般无需处理。
## 相关能力 / 下一步阅读
- [笑话大全：5 分钟接入，从注册到拿到第一条笑话](https://www.showapi.com/guides/joke-api-quickstart-341)
- [笑话大全调用失败排查：showapi_res_code 与 ret_code 非 0 怎么办](https://www.showapi.com/guides/joke-api-error-341)
- [免费接口也要讲边界：笑话大全缓存策略与档位限制应对](https://www.showapi.com/guides/joke-api-cache-tier-341)
- **本系列共 10 篇**：查看[笑话大全 API 指南总目录](https://www.showapi.com/guides/joke-api-guides-341)
