字典查询：返回字段全解，ret_code 与 showapi_res_body 一文读懂
# 字典查询：返回字段全解，ret_code 与 showapi_res_body 一文读懂
> 元信息：接口 **字典查询**（apiCode 1524）· 免费服务 · 返回 JSON · 适用：所有调用方（尤其首次接入与排障）· 阅读时间约 6 分钟
## 核心要点
- 返回分两层：系统级（`showapi_res_code` 等）与业务级（`showapi_res_body` 内），业务结果看 `ret_code` 是否为 "0"。
- 6 个接入点返回结构分两类：**列表类（1524-1/2/3/4）走 `datas` 数组**；**详情类（1524-5/6）是扁平对象**，数据直接挂在 `showapi_res_body` 下。
- `basic_explain` / `detail_explain` 文档标 String 但示例返回数组，解析时必须兼容两种类型。
## Why：为什么要把返回结构讲清楚
很多接入报错不是接口问题，而是没搞懂「系统字段 vs 业务字段」「数组 vs 扁平对象」。比如有人拿 1524-5 当 `datas[0]` 取数据，结果取不到——因为汉字详情是扁平对象。本文一次说清，省去反复试错。
## What：前置条件与接口速览
| 项 | 值 |
|----|----|
| 接口名称 | 字典查询 |
| apiCode | 1524 |
| 接入点 | 1524-1 拼音列表 / 1524-2 部首列表 / 1524-3 拼音查字 / 1524-4 部首查字 / 1524-5 汉字详情 / 1524-6 词语成语解释 |
| 返回格式 | JSON |
| 业务包装 | 所有业务数据在 `showapi_res_body` 内 |
| 鉴权 | URL 上的 `appKey` |
接口详情页：[https://www.showapi.com/apiGateway/view/1524](https://www.showapi.com/apiGateway/view/1524)
## How：如何解析返回
### 步骤 1：先判断系统级成功
```python
import requests
APP_KEY = "YOUR_APPKEY"
resp = requests.post(
f"https://route.showapi.com/1524-5?appKey={APP_KEY}",
data={"hanzi": "你"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
body = resp.json()
# 系统级：HTTP 成功不代表业务成功
if body.get("showapi_res_code") != 0:
raise RuntimeError(f"网关错误：{body.get('showapi_res_error')}")
res_body = body["showapi_res_body"]
```
### 步骤 2：再判断业务级成功
```python
if res_body.get("ret_code") != "0":
raise RuntimeError(f"业务失败：{res_body.get('remark')}")
```
### 步骤 3：按接入点类型取数
```python
# 列表类（1524-1/2/3/4）：数据在 datas 数组
# 例如 1524-3 拼音查字
for item in res_body.get("datas", []):
print(item.get("hanzi"), item.get("pinyin"), item.get("bihua"))
# 详情类（1524-5/6）：字段直接挂在 res_body
# 1524-5 汉字详情
print(res_body.get("hanzi"), res_body.get("pinyin"), res_body.get("wubi"))
# 1524-6 词语/成语解释
print(res_body.get("cidian_explain"), res_body.get("allusion_explain"))
```
### cURL 与 Node.js
```bash
curl -X POST "https://route.showapi.com/1524-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
```
```javascript
const resp = await fetch(`https://route.showapi.com/1524-1?appKey=YOUR_APPKEY`, {
method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" },
});
const body = await resp.json();
const resBody = body.showapi_res_body;
if (resBody.ret_code === "0") console.log(resBody.datas);
```
## 返回示例与字段解析
**公共结构（所有接入点）**
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": { "ret_code": "0", "remark": "查询成功！", "...": "..." }
}
```
**列表类：1524-1 拼音列表（datas 数组）**
```json
{ "showapi_res_body": { "ret_code":"0", "remark":"查询成功！",
"datas": [ {"py_initial":"A","pinyin":"a"}, {"py_initial":"Z","pinyin":"zuo"} ] } }
```
**列表类：1524-3 拼音查字（datas 数组，含 py_tone）**
```json
{ "showapi_res_body": { "ret_code":"0",
"datas": [ {"hanzi":"吖","bihua":"6","py_tone":"ā","pinyin":"a"} ] } }
```
**详情类：1524-5 汉字详情（扁平对象）**
```json
{ "showapi_res_body": { "ret_code":"0", "hanzi":"你", "pinyin":"nǐ", "bushou":"亻",
"bihua":"7", "wubi":"wqiy", "words":"你娘 你老 你好",
"basic_explain":["你nǐ","ㄋㄧˇ","称对方……"], "detail_explain":["你","妳","nǐ","【代】","……"] } }
```
**详情类：1524-6 词语/成语解释（扁平对象，allusion_explain 可能为空）**
```json
{ "showapi_res_body": { "ret_code":"0", "ciyu":"针砭时弊",
"cidian_explain":"……指出时代和社会问题……", "allusion_explain":"", "pinyin":"zhēn biān shí bì" } }
```
| 接入点 | 结构 | 关键字段 |
|------|------|---------|
| 1524-1 拼音列表 | `datas[]` | `py_initial`, `pinyin` |
| 1524-2 部首列表 | `datas[]` | `bushou`, `bihua`（如「笔画一」） |
| 1524-3 拼音查字 | `datas[]` | `hanzi`, `bihua`, `py_tone`, `pinyin` |
| 1524-4 部首查字 | `datas[]` | `hanzi`, `bushou`, `bihua`, `pinyin` |
| 1524-5 汉字详情 | 扁平对象 | `hanzi`, `pinyin`, `bushou`, `bihua`, `wubi`, `words`, `basic_explain`, `detail_explain` |
| 1524-6 词语成语解释 | 扁平对象 | `ciyu`, `cidian_explain`, `allusion_explain`, `pinyin` |
## 进阶 / 边界
- **两类结构别混**：详情类（1524-5/6）没有 `datas`，直接取 `res_body` 的字段；列表类（1524-1/2/3/4）数据在 `datas` 数组。
- **`py_tone` 可能为空/「未分类」**：1524-3 中部分字 `py_tone` 为「未分类」，前端展示需容错。
- **`allusion_explain` 可能为空串**：1524-6 对普通词语常返回空，展示时回退到 `cidian_explain`。
- **错误码未枚举**：文档仅说明 `ret_code` "0" 成功、其他失败，未给出具体非 0 枚举值，排障以 `remark` 为准。
## FAQ
**Q1：showapi_res_code 和 ret_code 有什么区别？**
`showapi_res_code` 是系统/网关层（0 通常表示网关正常）；`showapi_res_body.ret_code` 是业务结果，"0" 才是业务成功。判断业务是否拿到数据用 `ret_code == "0"`。
**Q2：为什么我取 datas[0] 取不到汉字详情？**
汉字详情（1524-5）与词语解释（1524-6）是**扁平对象**，字段直接挂在 `showapi_res_body` 下，没有 `datas`。只有 1524-1/2/3/4 才用 `datas` 数组。
**Q3：basic_explain / detail_explain 有时候是数组有时候是字符串？**
是的，文档标注为 String，但返回示例是数组。解析时统一兼容：`v if 不是 list else "\n".join(v)`，避免直接调用字符串方法报错。
**Q4：ret_code 非 0 时有哪些可能值？**
文档未枚举具体非 0 错误码。非 0 即表示失败，读取 `remark` 字段获取原因（多为 AppKey 无效或必填参数缺失）。
## 相关能力 / 下一步阅读
- [字典查询：5 分钟接入，从注册到查出第一个汉字详情](https://www.showapi.com/guides/dict-quickstart-1524)
- [字典查询：汉字详细信息（1524-5）接入](https://www.showapi.com/guides/dict-char-detail-1524)
- [字典查询：拼音查字与部首查字（1524-3/1524-4）两种检索路径怎么选](https://www.showapi.com/guides/dict-pinyin-radical-query-1524)
- **本系列共 12 篇**：查看[字典查询指南总目录](https://www.showapi.com/guides/dict-guides-1524)
