测吉凶返回字段全解：ret_code、remark 与 expList 数组一文读懂
# 测吉凶返回字段全解：ret_code、remark 与 expList 数组一文读懂
> 接口/接入点：测吉凶 apiCode=1617（1617-1/2/3/4 通用） · 免费服务 · 返回格式 JSON · 适用人群：所有接入开发者 · 阅读时间：约 6 分钟
## 核心要点
- 返回分两层：`showapi_res_*` 是系统级包裹，`showapi_res_body` 才是业务数据。
- `ret_code`（在 body 内）为 `"0"` 才算成功；失败看 `remark`，不要只判断外层 `showapi_res_code`。
- `expList` 是**字符串数组**（实测确认），各接入点条目数量与文案不同；`title` 实测恒为空。
## Why：为什么要先搞懂返回结构
很多接入报错不是请求写错，而是**把外层状态码当业务结果**、或**按单值去读 expList 导致渲染空白**。把返回结构一次吃透，能省掉后面 80% 的「为什么页面没内容」工单。
## What：接口速览
| 项 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/1617-N?appKey=YOUR_APPKEY` |
| 返回格式 | JSON，UTF-8 |
| 系统级字段 | `showapi_res_code` / `showapi_res_error` / `showapi_res_id` / `showapi_fee_num` |
| 业务字段 | `showapi_res_body`：{ `ret_code`, `remark`, `title`, `expList` } |
## How：字段逐项说明
### 系统级包裹（showapi_res_*）
| 字段 | 类型 | 含义 |
|------|------|------|
| `showapi_res_code` | int | 通道级状态码，`0` 表示请求已正常处理（不代表业务一定成功） |
| `showapi_res_error` | string | 通道级错误信息，成功时为空 |
| `showapi_res_id` | string | 本次请求唯一标识，排查问题用 |
| `showapi_fee_num` | int | 本次消耗计费次数（实测=1） |
### 业务体（showapi_res_body）
| 字段 | 类型 | 含义 |
|------|------|------|
| `ret_code` | string | **业务结果**，`"0"` 成功，其他失败 |
| `remark` | string | 提示信息，如「查询成功！」或失败原因 |
| `title` | string | 标题字段，**实测恒为空字符串**，前端无需展示 |
| `expList` | **array<string>** | 吉凶分析条目数组，每条「前缀：内容」 |
### 判断成功的正确姿势（Python）
```python
import requests
r = requests.post("https://route.showapi.com/1617-1",
params={"appKey": "YOUR_APPKEY"},
data={"mobile": "13770000000"}, timeout=15)
r.raise_for_status()
body = r.json().get("showapi_res_body", {})
if body.get("ret_code") != "0":
print("业务失败：", body.get("remark")) # 看 remark，不是看 showapi_res_code
else:
for line in body.get("expList") or []:
print(line)
```
### cURL 看完整结构
```bash
curl -X POST "https://route.showapi.com/1617-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "qq=10001"
```
### Node.js
```javascript
const res = await fetch("https://route.showapi.com/1617-2?appKey=YOUR_APPKEY",
{ method: "POST", body: new URLSearchParams({ carNo: "京A12345" }),
signal: AbortSignal.timeout(15000) });
const json = await res.json();
const b = json.showapi_res_body;
console.log("ret_code:", b.ret_code, "remark:", b.remark, "expList:", b.expList);
```
## 返回示例与解析
以 1617-3（QQ号）实测为例：
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"title": "",
"expList": [
"号码：10001",
"数理：第1数",
"签语：大展鸿图，信用得固，无远弗界，可获成功",
"吉凶：吉",
"详解：主人的性格类型：[不善表达/疑心重型]，其具体表现为：在乎身边各人对自己的评价……"
]
}
}
```
注意 `expList` 是数组，`title` 为空，不要写 `expList.split` 之类按字符串处理的代码。
## 进阶 / 边界
- **`expList` 类型澄清**：OpenAPI 3.0 文档（2026-08-26 生成版）把它标成 `type: string`，但**实测返回为字符串数组**——以实测为准，文章/代码均按数组处理。
- **各接入点 expList 条目不同**：手机号/QQ 为 5 条（号码/数理/签语/吉凶/详解）；车牌号为 3 条（命理/数理/性格暗示，**无归属地**）；公司名**可能为空数组**（仅 ret_code+remark）。
- **`title` 恒空**：四个接入点实测该字段均为 `""`，不要依赖它做展示或判断。
## FAQ
**Q：为什么我判断 showapi_res_code==0 了，页面还是没内容？**
外层 `showapi_res_code` 只代表通道正常，业务可能失败。必须再判断 `showapi_res_body.ret_code == "0"`，失败信息在 `remark`。
**Q：expList 到底怎么遍历？**
它是数组，直接 `for line in expList` 或 `expList.forEach` 逐条渲染。文档误标为 string，不要当字符串 split。
**Q：title 字段有什么用？**
实测四个接入点都返回空字符串，新版文档也未给取值，建议前端忽略该字段。
**Q：showapi_fee_num 是什么？**
本次调用消耗的计费次数，免费档位内扣减；失败（ret_code≠0）是否计费以实际返回为准，建议以 `ret_code` 判断成功后再计入业务统计。
**Q：公司名查询为什么有时没有 expList？**
实测 1617-4 对部分公司名仅返回 `ret_code`+`remark`、无 expList。前端务必做「expList 为空数组」兜底，详见[公司名测吉凶专篇](https://www.showapi.com/guides/fortune-company-guide-1617)。
## 相关能力 / 下一步阅读
- [测吉凶：5 分钟接入指南（手机号/车牌号/QQ号/公司名）](https://www.showapi.com/guides/fortune-quickstart-1617)
- [expList 数组结构化解析：把「数理/签语/吉凶/详解」拆成字段](https://www.showapi.com/guides/fortune-expList-parse-1617)
- [测吉凶错误处理与边界容错：ret_code 判断、空 expList、参数校验](https://www.showapi.com/guides/fortune-error-handling-1617)
- **本系列共 13 篇**：查看[测吉凶指南总目录](https://www.showapi.com/guides/fortune-guides-1617)
