渣男语录返回字段全解：ret_code / text / remark 一文读懂
# 渣男语录返回字段全解：ret_code / text / remark 一文读懂
- **接口/接入点**：免费渣男语录（apiCode=2962，接入点 1） · **是否免费**：免费 · **请求方式**：POST/GET · **返回格式**：JSON · **适用人群**：已接入开发者、需要解析返回的同学 · **阅读时间**：约 4 分钟
## 核心要点
- 返回是**两层结构**：外层是 ShowAPI 统一信封（`showapi_res_*`），内层 `showapi_res_body` 才是业务数据。
- 业务体内只有三个字段：`ret_code`（状态）、`text`（语录正文）、`remark`（错误信息）。
- `ret_code` **只有 0 和 -1 两种取值**：0=成功，-1=接口准备中。没有更复杂的状态码。
## Why：为什么要搞懂返回结构
- 很多新手拿到返回直接取 `text`，结果偶发取到空值——其实是 `ret_code=-1`（接口准备中）时 `text` 不可用。
- 分清"系统级成功"和"业务级成功"，才能写出健壮的解析逻辑，避免把准备中状态当成正常内容展示给用户。
## What：接口速览
| 项 | 值 |
|----|----|
| 业务体路径 | `showapi_res_body` |
| 业务字段 | `ret_code`(Number)、`text`(String)、`remark`(String) |
| 业务状态码 | `0`=调用成功，`-1`=接口准备中 |
| 系统信封字段 | `showapi_res_code` / `showapi_res_error` / `showapi_res_id` / `showapi_fee_num` |
## How：正确解析返回
**Python（健壮解析）**
```python
import requests
resp = requests.post(
"https://route.showapi.com/2962-1",
params={"appKey": "YOUR_APPKEY"},
timeout=10,
)
data = resp.json()
body = data.get("showapi_res_body", {})
ret = body.get("ret_code")
if ret == 0:
print("语录：", body.get("text"))
elif ret == -1:
print("接口准备中，请稍后重试；remark=", body.get("remark"))
else:
print("未知状态：", ret, body.get("remark"))
```
**cURL + jq 校验**
```bash
curl -s "https://route.showapi.com/2962-1?appKey=YOUR_APPKEY" \
| jq '.showapi_res_body.ret_code, .showapi_res_body.text'
```
**Node.js（fetch）**
```javascript
const data = await (await fetch("https://route.showapi.com/2962-1?appKey=YOUR_APPKEY", { method: "POST" })).json();
const body = data.showapi_res_body || {};
if (body.ret_code === 0) console.log(body.text);
else if (body.ret_code === -1) console.log("接口准备中：", body.remark);
```
## 返回示例与解析
```json
{
"showapi_res_id": "",
"showapi_res_error": "",
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"text": "你不要闹了，她只是我的小学同学。",
"remark": ""
}
}
```
### 系统信封字段（外层）
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | 整数 | API 返回状态码（统一信封） |
| `showapi_res_error` | 字符串 | API 返回错误信息，正常为空 |
| `showapi_res_id` | 字符串 | 请求唯一标识 |
| `showapi_fee_num` | 整数 | 调用计费次数（免费接口通常为 0） |
### 业务字段（showapi_res_body 内）
| 字段 | 类型 | 取值 | 说明 |
|------|------|------|------|
| `ret_code` | 数字 | `0` / `-1` | `0`=调用成功，`-1`=接口准备中 |
| `text` | 字符串 | 任意文本 | 返回的"渣男"用语；`ret_code=-1` 时不可用 |
| `remark` | 字符串 | 文本/空 | 错误信息；成功时为空 |
## 进阶 / 边界
- **两层都该判**：外层 `showapi_res_code` 表示请求是否到达；内层 `ret_code` 表示业务是否成功。两层都正常才算拿到可用语录。
- **`-1` 不是错误**：`ret_code=-1` 表示接口准备中（如后端维护/初始化），属于可重试状态，建议做指数退避后重试，而非直接报错。
- **没有更多状态**：本接口业务状态码**只有 0 和 -1**，不要臆造 101/404 之类的枚举。
## FAQ
- **Q：为什么有时 text 是空的？** A：检查 `ret_code`，`-1`（接口准备中）时 `text` 不可用，稍后重试。
- **Q：ret_code 除了 0 和 -1 还有别的吗？** A：文档明确只有这两种取值，没有更多枚举。
- **Q：remark 什么时候有内容？** A：通常在 `ret_code=-1` 或异常时有说明，成功时为空。
- **Q：showapi_res_code 和 ret_code 有什么区别？** A：前者是系统信封（请求层），后者是业务层；两层都判才稳妥。
- **Q：返回里没有我想要的字段？** A：业务体只有 `ret_code`/`text`/`remark` 三个字段，没有坐标、状态机、批量等扩展字段。
## 相关能力 / 下一步阅读
- [渣男语录：5 分钟接入，从注册到第一条土味情话](https://www.showapi.com/guides/zhanan-quotes-quickstart-2962)
- [聊天机器人如何接入渣男语录？从调用到展示的全链路设计](https://www.showapi.com/guides/zhanan-quotes-chatbot-integration-2962)
- [渣男语录使用档位与频率限制：如何避免触发限流](https://www.showapi.com/guides/zhanan-quotes-rate-limit-2962)
- **本系列共 7 篇**：查看[渣男语录指南总目录](https://www.showapi.com/guides/zhanan-quotes-guides-2962)
