字典查询：词语或成语一键解释（1524-6）接入与 allusion_explain 空值处理
字典查询成语解释词语解释allusion_explain # 字典查询：词语或成语一键解释（1524-6）接入与 allusion_explain 空值处理
> 元信息：接口 **字典查询** 接入点 **1524-6 词语或成语解释** · 免费服务 · POST/GET · JSON · 适用：词典/语文学习/内容平台开发者 · 阅读时间约 6 分钟
## 核心要点
- 1524-6 只需一个必填参数 `ciyu`（词语或成语），返回 `cidian_explain`（词典解释）、`allusion_explain`（成语典故解释）、`pinyin`。
- 返回是**扁平对象**（无 `datas` 数组），字段直接挂在 `showapi_res_body` 下。
- `allusion_explain` **可能为空串**：普通词语常无典故，展示时务必回退到 `cidian_explain`。
## Why：为什么用词语/成语解释接入点
写作辅助、语文作业、阅读标注场景常需要「一句话解释某个词/成语」。1524-6 一次返回词典释义与（若有）成语典故，适合做划词解释、生词卡、作文助手等。
## What：前置条件与接口速览
| 项 | 值 |
|----|----|
| apiCode | 1524 |
| 接入点 | 1524-6 词语或成语解释 |
| 请求地址 | `https://route.showapi.com/1524-6?appKey=YOUR_APPKEY` |
| 必填参数 | `ciyu`（String，词语或成语，如「针砭时弊」） |
| 返回结构 | 扁平对象 |
| 计费 | 免费（档位限额） |
接口详情页：[https://www.showapi.com/apiGateway/view/1524/6](https://www.showapi.com/apiGateway/view/1524/6)
## How：快速接入
### 步骤 1：构造请求（Python）
```python
import requests
APP_KEY = "YOUR_APPKEY"
resp = requests.post(
"https://route.showapi.com/1524-6",
params={"appKey": APP_KEY},
data={"ciyu": "针砭时弊"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
res_body = resp.json().get("showapi_res_body", {})
if res_body.get("ret_code") != "0":
raise RuntimeError(res_body.get("remark"))
ciyu = res_body.get("ciyu")
pinyin = res_body.get("pinyin")
cidian = res_body.get("cidian_explain") or ""
allusion = res_body.get("allusion_explain") or ""
# allusion_explain 可能为空，优先展示典故，缺失则回退词典解释
explain = allusion if allusion else cidian
print(f"{ciyu}（{pinyin}）")
print("解释：", explain or "（无解释返回）")
```
### 步骤 2：cURL
```bash
curl -X POST "https://route.showapi.com/1524-6?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "ciyu=%E9%92%88%E7%A0%AD%E6%97%B6%E5%BC%8A"
```
### 步骤 3：Node.js
```javascript
const r = await (await fetch(`https://route.showapi.com/1524-6?appKey=YOUR_APPKEY`, {
method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ ciyu: "针砭时弊" }),
})).json();
const rb = r.showapi_res_body;
if (rb.ret_code !== "0") throw new Error("查询失败：" + rb.remark);
const explain = (rb.allusion_explain || "") || rb.cidian_explain || "（无解释返回）";
console.log(rb.ciyu, rb.pinyin, explain);
```
## 返回示例与字段解析
```json
{
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"cidian_explain": "（1）砭：古代治病刺穴的石针……指出时代和社会问题，又针又砭，求得改正向善。",
"ciyu": "针砭时弊",
"allusion_explain": "",
"pinyin": "zhēn biān shí bì"
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `ciyu` | String | 查询的词语/成语（原样回显） |
| `pinyin` | String | 拼音（空格分隔音节） |
| `cidian_explain` | String | 词典对词语/成语的解释 |
| `allusion_explain` | String | 成语字典对成语的典故解释，**可能为空串** |
## 进阶 / 边界
- **`allusion_explain` 空值常态**：普通词语（如「快乐」）通常无典故，`allusion_explain` 为空，必须回退到 `cidian_explain`，否则界面空白。
- **返回可能两者皆空**：个别词条两字段都为空串，前端需有「（暂无解释）」兜底文案，不要抛错。
- **不是所有成语都有典故字段**：以 `allusion_explain` 是否有内容为准，不要假设成语一定有典故。
- **释义较长**：`cidian_explain` 可能含多条释义，展示时建议保留换行或分页。
## FAQ
**Q1：allusion_explain 为什么有时候是空的？**
它专指成语典故解释。普通词语没有典故，接口返回空串属正常。展示时回退到 `cidian_explain` 即可。
**Q2：1524-6 和 1524-5 有什么区别？**
1524-5 查「单个汉字」的详情；1524-6 查「词语或成语」的解释，二者粒度不同，不能互相替代。
**Q3：返回的拼音带空格（如 zhēn biān shí bì）正常吗？**
正常，多音节按空格分隔。需要连写时自行去掉空格即可。
**Q4：ciyu 参数可以传单字吗？**
该接入点面向词语/成语。单字释义请用 1524-5 汉字详情接入点。
## 相关能力 / 下一步阅读
- [字典查询：汉字详细信息（1524-5）接入](https://www.showapi.com/guides/dict-char-detail-1524)
- [字典查询：返回字段全解，ret_code 与 showapi_res_body 一文读懂](https://www.showapi.com/guides/dict-response-codes-1524)
- [字典查询：语文学习 App 如何集成？](https://www.showapi.com/guides/dict-learning-app-1524)
- **本系列共 12 篇**：查看[字典查询指南总目录](https://www.showapi.com/guides/dict-guides-1524)
